A platform for community discussion. Free, open, simple.
DEV: Site settings skills - for categories can allow for more flexible options (#41504)
Natalie Tay46bea6613323
diff --git a/.skills/discourse-site-settings/SKILL.md b/.skills/discourse-site-settings/SKILL.mdnew file mode 100644index 00000000000..ec0e6145e34--- /dev/null+++ b/.skills/discourse-site-settings/SKILL.md@@ -0,0 +1,225 @@+---+name: discourse-site-settings+description: Use when adding, modifying, renaming, or reviewing Discourse site settings in core or plugins. Covers config/site_settings.yml and plugin config/settings.yml, setting names, types, defaults, client exposure, areas, validators, i18n descriptions, category/category_list conventions, category scope dropdowns, access patterns, cache implications, tests, browser verification, and migration handoffs.+---++# Discourse Site Settings++Use this skill before writing or reviewing ordinary Discourse site settings. For upcoming-change+feature flags, also use `discourse-upcoming-changes`. For database migrations that rename or+remove settings, use `discourse-migration`.++## Workflow++1. Find nearby examples with `rg`; avoid reading all of `config/site_settings.yml`.+2. Put core settings in `config/site_settings.yml`; put plugin settings in+ `plugins/<plugin>/config/settings.yml`.+3. Add an i18n description under `en.site_settings.<setting_name>` in the matching+ `config/locales/server.en.yml`.+4. Set `client: true` only when frontend code must read the setting through `siteSettings`.+5. Prefer an `area:` for admin grouping when the setting belongs on a filtered settings page.+6. Access settings as `SiteSetting.setting_name` in Ruby and through `@service siteSettings` in JS.+7. Add a validator when a setting depends on another site setting for correctness.+8. Write focused tests for behavior controlled by the setting, including default behavior.+9. Use Playwright/browser to visit the admin site settings page and verify the setting name and+ i18n description render correctly.++## Naming++- Use a name that describes the behavior, not only the implementation.+- Use the conventional suffix for typed settings:+ - `*_groups` for group lists.+ - `*_categories` for `type: category_list`.+ - `*_category` for `type: category`.+- Avoid `_ids` in public site setting names for category lists even though values are stored as ids.+- For paired settings, prepend the same feature name so admins can recognize the settings as a+ related group.++## Descriptions++- Write descriptions for admins, not developers.+- State the default or safest interpretation when ambiguity is likely.+- Mention privacy/security boundaries that always apply.+- If a setting only matters when another setting has a certain value, say so in the description.+- When referencing another site setting, use the `{{setting:setting_name}}` token instead of writing+ the raw setting name or hardcoding the translated label. This lets the admin UI render the+ referenced setting consistently and avoids copy drifting when labels change.+- Keep option names consistent with enum values and admin labels.++## Common Options++- `default`: choose a safe default for existing sites. For upload settings, use the id of the+ seeded upload from `db/fixtures/010_uploads.rb`.+- `min`, `max`, `regex`, and `validator`: enforce value constraints server-side; descriptions and+ frontend affordances are not enough.+- `mandatory_values`: pipe-separated values that must always remain in the setting. Common for+ `group_list` settings that must always include admins/moderators.+- `disallowed_groups`: pipe-separated group ids hidden from group selectors and stripped from API+ updates. This only applies to `group_list` settings.+- `requires_confirmation`: use for risky changes that need an admin confirmation dialog. Valid+ values are `simple`, `simple_on_enable`, and `simple_on_disable`; add matching client i18n under+ `admin.site_settings.requires_confirmation_messages.<setting_name>` when the default copy is not+ specific enough.+- `themeable: true`: only for client-side UI settings that themes may override. Prefer simple types+ such as `bool`, `integer`, `list`, or `enum`; normal `SiteSetting.setting = value` writes are not+ allowed for themeable settings.+- `localizable`: use for public text/content settings that content localization may translate. Use+ a hash for metadata such as `max_length:` and `cooked: true` when localized markdown should be+ cooked.+- `area`: use the filtered admin settings page key when the setting belongs with an existing admin+ workflow.+- `refresh: true`: use when clients should reload after the setting changes.++## Setting Types++Start with the simplest type that matches the admin's mental model:++- `bool`: on/off behavior.+- `integer` / `float`: numeric values; set `min`/`max` where possible.+- `enum`: one value from a fixed set; use `enum: "ClassName"` for reusable translated enums.+- `list`: multiple values from choices; use `list_type: compact` for selector-style UI and+ `list_type: simple` for reorderable item lists.+- `group` / `group_list`: one or many groups; use `mandatory_values` and `disallowed_groups` where+ relevant.+- `category` / `category_list`: one or many categories through the category picker.+- `tag_list`, `emoji_list`, `tag_group_list`, `host_list`, `email`, `username`, `color`, `icon`,+ `upload`, `uploaded_image_list`, and `file_size_restriction`: use when the name describes the+ data shape directly.+- `json_schema` / `objects`: structured settings. Prefer these only when a scalar/list setting is+ not enough, and keep tests around schema validation and serialization.++### Category Lists++Use a plain `type: category_list` when the setting means exactly "these categories". Do not add a+scope enum just because the setting involves categories. For example, user-default settings such as+`default_categories_watching` should stay as a single category list; admins are selecting the+categories to apply, not defining an include/exclude query scope.++```yaml+default_categories_watching:+ type: category_list+ default: ""+ area: "user_defaults"+```++Use the two-setting category-scope pattern only when the feature filters a topic/post result set and+admins may reasonably need all/public/include/exclude choices or subcategory control.++```yaml+xyz_category_scope:+ type: enum+ default: "public"+ enum: "CategoryScopeSiteSetting"+ client: false+ area: "feature-name"++xyz_categories:+ type: category_list+ default: ""+ client: false+ area: "feature-name"+ depends_on:+ - xyz_category_scope+ depends_on_values:+ xyz_category_scope:+ - include+ - include_strict+ - exclude+ - exclude_strict+ depends_behavior: "hidden"+ dependent_setting_display: "inline"+```++Semantics:++- `all`: all regular topics.+- `public`: all non-read-restricted regular topics.+- `include`: use `xyz_categories` and their subcategories.+- `include_strict`: use only `xyz_categories`.+- `exclude`: start from all regular topics, then remove `xyz_categories` and their subcategories.+- `exclude_strict`: start from all regular topics, then remove only `xyz_categories`.++The `CategoryScopeSiteSetting` enum provides translated admin labels for these stored values. Pair+it with `depends_on_values`, `depends_behavior: "hidden"`, and `dependent_setting_display: "inline"`+so the category picker appears under the scope setting only when include/exclude modes need it.++Do not make `exclude` mean "public minus selected categories" unless the product requirement+explicitly says that. It is harder to explain and usually surprises admins.++Example from Discourse AI admin dashboard highlights:++```yaml+ai_admin_dashboard_highlights_category_scope:+ type: enum+ default: "public"+ enum: "CategoryScopeSiteSetting"+ client: false+ area: "ai-features/admin_dashboard"++ai_admin_dashboard_highlights_categories:+ type: category_list+ default: ""+ client: false+ area: "ai-features/admin_dashboard"+ depends_on:+ - ai_admin_dashboard_highlights_category_scope+ depends_on_values:+ ai_admin_dashboard_highlights_category_scope:+ - include+ - include_strict+ - exclude+ - exclude_strict+ depends_behavior: "hidden"+ dependent_setting_display: "inline"+```++Recommended description shape:++```yaml+ai_admin_dashboard_highlights_category_scope: "Choose which categories AI highlights can use. Include and exclude options use {{setting:ai_admin_dashboard_highlights_categories}}. Personal messages are always excluded."+ai_admin_dashboard_highlights_categories: "Categories used when the AI highlights category scope is set to <strong>include</strong> or <strong>exclude</strong>."+```++Implementation notes:++- Use `Category.subcategory_ids(category_id)` when non-strict modes include descendants.+- Keep `IN (:category_ids)` / `NOT IN (:category_ids)` parameterized; parse category-list values+ to integers before passing them into SQL.+- Handle empty lists explicitly:+ - Empty include means match nothing.+ - Empty exclude means exclude nothing.+- If results are cached, include both the scope and the configured category list in the cache key.+- Test public default, all, include, include strict, exclude, exclude strict, private categories,+ personal messages if topics are involved, and subcategories.++### Enum Settings++- Prefer stable machine values such as `include_strict`; let descriptions/admin labels explain them.+- Keep enum values short, lowercase, and underscore-separated.+- When changing values before merge, update all tests and cache keys. After merge, treat value+ changes as migrations/compatibility work.++### Dependent Settings++- Add a validator when one setting only works if another setting is enabled, configured, or has a+ compatible value.+- Keep dependency enforcement server-side; admin descriptions are not enough.+- `depends_on` without `depends_on_values` is for boolean parent settings.+- Use `depends_on_values` when the parent is an enum/string setting and the dependent only applies+ to specific values.+- Use `depends_behavior: "hidden"` when the dependent setting should be hidden until applicable.+- Use `dependent_setting_display: "inline"` when a hidden dependent belongs visually under its+ parent; save/reset controls are grouped with the parent setting.+- Test both the valid and invalid combinations.++## Review Checklist++- Is the default safe for existing sites?+- Is the setting hidden from the client unless JS needs it?+- Does a dependency on another setting need a validator?+- Does the admin description answer the likely "what does this include?" question?+- Is the setting grouped into the right admin area?+- Was the admin settings page checked in the browser so the name and description render correctly?+- Are cache keys or background jobs affected by setting changes?+- Are private categories, personal messages, subcategories, deleted records, and anonymous access+ handled where relevant?