A platform for community discussion. Free, open, simple.
DEV: Make upcoming change CSS classes opt-in (#40669)
Martin Brennan7faa89d9451c
diff --git a/.skills/discourse-upcoming-changes-authoring/SKILL.md b/.skills/discourse-upcoming-changes-authoring/SKILL.mdindex 21a65f8a11b..1343874f104 100644--- a/.skills/discourse-upcoming-changes-authoring/SKILL.md+++ b/.skills/discourse-upcoming-changes-authoring/SKILL.md@@ -68,7 +68,7 @@ All services use `Service::Base`. They're organized under `app/services/upcoming**Site settings service** (`app/services/site-settings.js`) — Loads upcoming changes from `PreloadStore`, applies them as overrides to site settings, and stores them in `settings.currentUserUpcomingChanges`.-**Body CSS classes** — `app/controllers/application.js` generates `uc-{dasherized-key}` classes on `<body>` for each enabled upcoming change, allowing CSS-based feature gating.+**Body CSS classes** — `app/controllers/application.js` generates `uc-{dasherized-key}` classes on `<body>` for each enabled upcoming change that opts in via `body_class: true`, allowing CSS-based feature gating. The controller intersects `siteSettings.currentUserUpcomingChanges` (enabled-for-this-user changes) with `site.upcoming_changes_with_css` (changes that opted into CSS) — a change must be in both to get a body class. The opt-in list comes from `SiteSerializer#upcoming_changes_with_css`, which returns the change names whose metadata has `body_class: true`. See [CSS Opt-In](#css-opt-in) below.**Notifications** — Two notification types (`upcoming-change-available`, `upcoming-change-automatically-promoted`) handle singular/dual/many change descriptions and link to the admin page with filter params.@@ -147,6 +147,33 @@ Some upcoming changes only make sense to show admins under certain conditions- **N+1 by design**: `should_display?` is called once per change in the loop. If a gating method does expensive work (DB queries, plugin lookups), memoize inside the method to avoid repeated cost.- **Notifications still fire**: Conditional display only filters the `List` service result. `TrackAddedChanges`, `NotifyAdminsOfAvailableUpcomingChanges`, `NotifyPromotions`, etc. do not consult `ConditionalDisplay`, so admins may still receive notifications about a hidden change. Consider this when designing the gate — usually the gate should reflect a long-lived condition (plugin missing, theme not installed) rather than transient state.+### CSS Opt-In++A change can opt into having a `uc-{dasherized-key}` class added to `<body>` when it is enabled for the current user, so stylesheets can gate visuals on the change. This is **opt-in** via the `body_class: true` metadata key — body classes are *not* emitted for every enabled change, only those that ask for them. This keeps the body class list small and intentional, and avoids leaking the names of unrelated (non-visual) changes into the DOM.++```yaml+enable_your_feature_name:+ default: false+ client: true+ hidden: true+ upcoming_change:+ status: experimental+ impact: feature,all_members+ body_class: true+```++#### How It Works++1. **Parsing** — `lib/site_setting_extension.rb` reads `body_class` from the `upcoming_change:` metadata and stores it (defaulting to `nil`/falsey) in `upcoming_change_metadata`.+2. **Serialization** — `SiteSerializer#upcoming_changes_with_css` filters `SiteSetting.upcoming_change_site_settings` down to the change names whose metadata has `body_class` truthy, and exposes them to the frontend as `site.upcoming_changes_with_css`.+3. **Body class generation** — `app/controllers/application.js` iterates `siteSettings.currentUserUpcomingChanges` and pushes a `uc-{dasherize(key)}` class only when both the setting is truthy for the user **and** `site.upcoming_changes_with_css.includes(key)`. A change must be enabled *and* opted-in to get a class.++#### Key Behaviors++- **Opt-in only**: Omitting `body_class` (or setting it `false`) means no body class — the default. Add it only when you actually have CSS keyed on `uc-{name}`.+- **Enabled-for-user gated**: The class only appears for users the change is enabled for (via `currentUserUpcomingChanges`), not globally. Anonymous/ineligible users won't get it.+- **Integrity-checked**: `body_class` is in the integrity spec's `allowed_keys` and must be a boolean — see [Mocking Metadata](#mocking-metadata) for how to set it in tests.+## Key Design Decisions### Caching Strategy@@ -286,11 +313,14 @@ mock_upcoming_change_metadata(status: :experimental,impact_type: "feature",impact_role: "all_members",+ body_class: true, # optional — opts into the uc-{name} body class},},)```+To test the CSS opt-in serializer (`SiteSerializer#upcoming_changes_with_css`), mock two changes — one with `body_class: true` and one with `body_class: false` — and assert the serialized array includes the former and excludes the latter. See `spec/serializers/site_serializer_spec.rb`. System coverage for the resulting `uc-{name}` body class lives in `spec/system/member_upcoming_changes_spec.rb`.+### Mocking Default OverridesUse `mock_upcoming_change_default_overrides` to set up override metadata in tests — never modify `site_settings.yml`:@@ -405,6 +435,7 @@ Notification type tests create notifications with `Notification.create()` and ve| Event model | `app/models/upcoming_change_event.rb` || Group model | `app/models/site_setting_group.rb` || Settings integration | `lib/site_setting_extension.rb` (search for `upcoming_change`) |+| CSS opt-in serializer | `app/serializers/site_serializer.rb` (`upcoming_changes_with_css`) || Defaults provider | `lib/site_settings/defaults_provider.rb` (default override activation/resolution) || Services | `app/services/upcoming_changes/*.rb` || Group upsert | `app/services/site_setting/upsert_groups.rb` |@@ -423,6 +454,8 @@ Notification type tests create notifications with `Notification.create()` and ve| Constants | `frontend/discourse/app/lib/constants.js` || Styles | `app/assets/stylesheets/admin/upcoming-changes.scss` || Core spec | `spec/lib/upcoming_changes_spec.rb` |+| Integrity spec | `spec/integrity/upcoming_change_metadata_spec.rb` (validates allowed metadata keys) |+| Serializer spec | `spec/serializers/site_serializer_spec.rb` (`#upcoming_changes_with_css`) || Request spec | `spec/requests/admin/config/upcoming_changes_controller_spec.rb` || Admin system spec | `spec/system/admin_upcoming_changes_spec.rb` || Member system spec | `spec/system/member_upcoming_changes_spec.rb` |diff --git a/.skills/discourse-upcoming-changes/SKILL.md b/.skills/discourse-upcoming-changes/SKILL.mdindex 79632c8a07e..5f538c0f6aa 100644--- a/.skills/discourse-upcoming-changes/SKILL.md+++ b/.skills/discourse-upcoming-changes/SKILL.md@@ -83,6 +83,15 @@ upcoming_change:| `[specific_groups]` | No one, Specific group(s) || `[staff, specific_groups]` | No one, Staff, Specific group(s) |+**Optional:** Add `include_css: true` if you need to scope CSS to this change. When enabled for a user, a `uc-<dasherized-setting-name>` class is added to `<body>` so stylesheets can gate visuals on the change (e.g. `enable_your_feature_name` → `body.uc-enable-your-feature-name`). Omit it (the default) when the change has no CSS keyed on the body class — body classes are opt-in, not emitted for every change.++```yaml+upcoming_change:+ status: "experimental"+ impact: "feature,all_members"+ include_css: true+```+### 2. Add TranslationAdd to `config/locales/server.en.yml` under `site_settings:`:diff --git a/app/models/site.rb b/app/models/site.rbindex 026785ce1dc..ed464dae8aa 100644--- a/app/models/site.rb+++ b/app/models/site.rb@@ -222,6 +222,7 @@ class Sitefull_name_visible_in_signup:,tos_url: Discourse.tos_url,privacy_policy_url: Discourse.privacy_policy_url,+ upcoming_changes_with_css: UpcomingChanges.including_css,}.to_json)enddiff --git a/app/serializers/site_serializer.rb b/app/serializers/site_serializer.rbindex bc66ac586ba..146bcbd5a85 100644--- a/app/serializers/site_serializer.rb+++ b/app/serializers/site_serializer.rb@@ -53,6 +53,7 @@ class SiteSerializer < ApplicationSerializer:full_name_visible_in_signup,:admin_config_login_routes,:email_configured,+ :upcoming_changes_with_css,)has_many :archetypes, embed: :objects, serializer: ArchetypeSerializer@@ -448,6 +449,10 @@ class SiteSerializer < ApplicationSerializerSite.full_name_visible_in_signupend+ def upcoming_changes_with_css+ UpcomingChanges.including_css+ end+privatedef ordered_flags(flags)diff --git a/config/site_settings.yml b/config/site_settings.ymlindex 05103a1a324..04332efc199 100644--- a/config/site_settings.yml+++ b/config/site_settings.yml@@ -31,6 +31,7 @@# - status: experimental | alpha | beta | stable# - impact: two parts separated by comma - feature|other|site_setting_default , staff|admins|moderators|all_members|developers# - learn_more_url: a url for more information+# - body_class: (optional boolean) to include a uc-NAME CSS class on the <body> element when the change is enabled# - allow_enabled_for: (optional array) restricts which "Enabled for"# dropdown options the admin can pick for this upcoming change.# Valid values: everyone, staff, specific_groups.@@ -4392,6 +4393,7 @@ experimental:allow_enabled_for:- staff- specific_groups+ body_class: trueenable_auto_grid_images:default: trueclient: true@@ -4405,6 +4407,7 @@ experimental:status: "stable"impact: "feature,all_members"learn_more_url: "https://meta.discourse.org/t/-/403284"+ body_class: trueenable_new_post_reactions_menu:default: falseclient: true@@ -4469,6 +4472,7 @@ experimental:status: "beta"impact: "feature,all_members"learn_more_url: "https://meta.discourse.org/t/-/387322"+ body_class: trueenable_simplified_category_creation:default: falsehidden: true@@ -4499,6 +4503,7 @@ experimental:impact: "feature,all_members"status: "beta"learn_more_url: "https://meta.discourse.org/t/-/395331"+ body_class: trueenable_horizon_high_context_topic_cards:default: falseclient: truediff --git a/frontend/discourse/app/controllers/application.js b/frontend/discourse/app/controllers/application.jsindex d368816714d..9ba7eda6ddc 100644--- a/frontend/discourse/app/controllers/application.js+++ b/frontend/discourse/app/controllers/application.js@@ -16,6 +16,7 @@ export default class ApplicationController extends Controller {@service router;@service scrollState;@service sidebarState;+ @service site;@service siteSettings;queryParams = [{ navigationMenuQueryParamOverride: "navigation_menu" }];@@ -38,7 +39,10 @@ export default class ApplicationController extends Controller {const classes = [];Object.keys(this.siteSettings.currentUserUpcomingChanges).forEach((key) => {- if (this.siteSettings[key]) {+ if (+ this.siteSettings[key] &&+ this.site.upcoming_changes_with_css.includes(key)+ ) {classes.push(`uc-${dasherize(key)}`);}});diff --git a/lib/site_setting_extension.rb b/lib/site_setting_extension.rbindex 335ba5fbafd..56bed6a2866 100644--- a/lib/site_setting_extension.rb+++ b/lib/site_setting_extension.rb@@ -165,6 +165,8 @@ module SiteSettingExtension# options are shown. Valid values: everyone, staff, specific_groups. "No one"# is always present. If `everyone` is included it must be the only value.# Omit to allow all options (the default permissive behavior).+ # body_class: (optional) boolean to include CSS data-attrs for the upcoming change,+ # useful for scoping style changes related to the change.def upcoming_change_metadata@upcoming_change_metadata ||= {}end@@ -1309,6 +1311,7 @@ module SiteSettingExtensionimpact_role: impact_role,status: opts[:upcoming_change][:status].to_sym,allow_enabled_for: allow_enabled_for,+ body_class: opts[:upcoming_change][:body_class],)enddiff --git a/lib/upcoming_changes.rb b/lib/upcoming_changes.rbindex 393934ccffb..e4d7da4d81d 100644--- a/lib/upcoming_changes.rb+++ b/lib/upcoming_changes.rb@@ -441,4 +441,10 @@ module UpcomingChangesdef self.find_dependents_for_change(change_setting_name)settings_provider.type_supervisor.dependencies.dependents(change_setting_name.to_s)end++ def self.including_css+ settings_provider.upcoming_change_site_settings.filter_map do |upcoming_change|+ upcoming_change if settings_provider.upcoming_change_metadata[upcoming_change][:body_class]+ end+ endenddiff --git a/spec/integrity/upcoming_change_metadata_spec.rb b/spec/integrity/upcoming_change_metadata_spec.rbindex c4b90cab6f9..674c62602f2 100644--- a/spec/integrity/upcoming_change_metadata_spec.rb+++ b/spec/integrity/upcoming_change_metadata_spec.rb@@ -45,7 +45,7 @@ RSpec.describe "upcoming change metadata integrity checks" doit "#{label} is valid" dometadata = setting[:upcoming_change]- allowed_keys = %i[status impact learn_more_url allow_enabled_for]+ allowed_keys = %i[status impact learn_more_url allow_enabled_for body_class]required_keys = %i[status impact]unsupported_keys = metadata.keys - allowed_keysmissing_keys = required_keys - metadata.keys@@ -55,6 +55,7 @@ RSpec.describe "upcoming change metadata integrity checks" doimpact_parts = impact.is_a?(String) ? impact.split(",") : []learn_more_url = metadata[:learn_more_url]allow_enabled_for = metadata[:allow_enabled_for]+ body_class = metadata[:body_class]aggregate_failures doexpect(setting[:options][:hidden]).to eq(true), "#{label} must set `hidden: true`"@@ -109,6 +110,11 @@ RSpec.describe "upcoming change metadata integrity checks" do"#{label} `upcoming_change.allow_enabled_for` may not combine `everyone` with other values"endend++ unless body_class.nil?+ expect([true, false]).to include(body_class),+ "#{label} `upcoming_change.body_class` must be a boolean"+ endendendenddiff --git a/spec/requests/api/schemas/json/site_response.json b/spec/requests/api/schemas/json/site_response.jsonindex def64d0f75d..ba761e4c7be 100644--- a/spec/requests/api/schemas/json/site_response.json+++ b/spec/requests/api/schemas/json/site_response.json@@ -513,6 +513,12 @@"email_configured": {"type": "boolean"},+ "upcoming_changes_with_css": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },"topic_featured_link_allowed_category_ids": {"type": "array","items": {diff --git a/spec/serializers/site_serializer_spec.rb b/spec/serializers/site_serializer_spec.rbindex 19bc280fc97..9f3673e43e5 100644--- a/spec/serializers/site_serializer_spec.rb+++ b/spec/serializers/site_serializer_spec.rb@@ -605,4 +605,31 @@ RSpec.describe SiteSerializer doexpect(serialized).not_to have_key(:admin_config_login_routes)endend++ describe "#upcoming_changes_with_css" do+ it "returns upcoming changes with body_class: true" do+ mock_upcoming_change_metadata(+ {+ enable_upload_debug_mode: {+ impact: "other,developers",+ status: :beta,+ impact_type: "other",+ impact_role: "developers",+ body_class: true,+ },+ enable_user_tips: {+ impact: "feature,all_members",+ status: :alpha,+ impact_type: "feature",+ impact_role: "all_members",+ body_class: false,+ },+ },+ )++ serialized = described_class.new(Site.new(guardian), scope: guardian, root: false).as_json+ expect(serialized[:upcoming_changes_with_css]).to include(:enable_upload_debug_mode)+ expect(serialized[:upcoming_changes_with_css]).not_to include(:enable_user_tips)+ end+ endenddiff --git a/spec/system/member_upcoming_changes_spec.rb b/spec/system/member_upcoming_changes_spec.rbindex c548003096e..37212cb802e 100644--- a/spec/system/member_upcoming_changes_spec.rb+++ b/spec/system/member_upcoming_changes_spec.rb@@ -13,12 +13,14 @@ RSpec.describe "Member upcoming changes" dostatus: :experimental,impact_type: "other",impact_role: "developers",+ body_class: true,},about_page_extra_groups_show_description: {impact: "feature,all_members",status: :stable,impact_type: "feature",impact_role: "all_members",+ body_class: true,},},)