Skip to content

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.md
new file mode 100644
index 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?