Skip to content

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.md
index 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 Overrides
Use `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.md
index 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 Translation
Add to `config/locales/server.en.yml` under `site_settings:`:
diff --git a/app/models/site.rb b/app/models/site.rb
index 026785ce1dc..ed464dae8aa 100644
--- a/app/models/site.rb
+++ b/app/models/site.rb
@@ -222,6 +222,7 @@ class Site
full_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
)
end
diff --git a/app/serializers/site_serializer.rb b/app/serializers/site_serializer.rb
index 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 < ApplicationSerializer
Site.full_name_visible_in_signup
end
+ def upcoming_changes_with_css
+ UpcomingChanges.including_css
+ end
+
private
def ordered_flags(flags)
diff --git a/config/site_settings.yml b/config/site_settings.yml
index 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: true
enable_auto_grid_images:
default: true
client: true
@@ -4405,6 +4407,7 @@ experimental:
status: "stable"
impact: "feature,all_members"
learn_more_url: "https://meta.discourse.org/t/-/403284"
+ body_class: true
enable_new_post_reactions_menu:
default: false
client: true
@@ -4469,6 +4472,7 @@ experimental:
status: "beta"
impact: "feature,all_members"
learn_more_url: "https://meta.discourse.org/t/-/387322"
+ body_class: true
enable_simplified_category_creation:
default: false
hidden: true
@@ -4499,6 +4503,7 @@ experimental:
impact: "feature,all_members"
status: "beta"
learn_more_url: "https://meta.discourse.org/t/-/395331"
+ body_class: true
enable_horizon_high_context_topic_cards:
default: false
client: true
diff --git a/frontend/discourse/app/controllers/application.js b/frontend/discourse/app/controllers/application.js
index 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.rb
index 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 SiteSettingExtension
impact_role: impact_role,
status: opts[:upcoming_change][:status].to_sym,
allow_enabled_for: allow_enabled_for,
+ body_class: opts[:upcoming_change][:body_class],
)
end
diff --git a/lib/upcoming_changes.rb b/lib/upcoming_changes.rb
index 393934ccffb..e4d7da4d81d 100644
--- a/lib/upcoming_changes.rb
+++ b/lib/upcoming_changes.rb
@@ -441,4 +441,10 @@ module UpcomingChanges
def 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
+ end
end
diff --git a/spec/integrity/upcoming_change_metadata_spec.rb b/spec/integrity/upcoming_change_metadata_spec.rb
index 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" do
it "#{label} is valid" do
metadata = 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_keys
missing_keys = required_keys - metadata.keys
@@ -55,6 +55,7 @@ RSpec.describe "upcoming change metadata integrity checks" do
impact_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 do
expect(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"
end
end
+
+ unless body_class.nil?
+ expect([true, false]).to include(body_class),
+ "#{label} `upcoming_change.body_class` must be a boolean"
+ end
end
end
end
diff --git a/spec/requests/api/schemas/json/site_response.json b/spec/requests/api/schemas/json/site_response.json
index 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.rb
index 19bc280fc97..9f3673e43e5 100644
--- a/spec/serializers/site_serializer_spec.rb
+++ b/spec/serializers/site_serializer_spec.rb
@@ -605,4 +605,31 @@ RSpec.describe SiteSerializer do
expect(serialized).not_to have_key(:admin_config_login_routes)
end
end
+
+ 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
+ end
end
diff --git a/spec/system/member_upcoming_changes_spec.rb b/spec/system/member_upcoming_changes_spec.rb
index 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" do
status: :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,
},
},
)