Menu
Use when modifying, debugging, or extending the upcoming changes framework code and system itself.
| name | discourse-upcoming-changes-authoring |
| description | Use when modifying, debugging, or extending the upcoming changes framework code and system itself. |
This skill is for working on the upcoming changes framework itself — the internal machinery that powers feature flag rollout in Discourse. For adding a new feature flag using the framework, see the discourse-upcoming-changes skill instead.
The upcoming changes system has three layers: a Ruby core that manages state and business logic, a services layer that orchestrates tracking/notifications/toggling, and an Ember frontend that renders the admin UI and applies per-user overrides.
lib/upcoming_changes.rb — The central module. All business logic for resolving values, checking user eligibility, caching, and image handling lives here.
Key methods to understand:
resolved_value(setting_name) — Determines the effective value of a setting. This is where auto-promotion logic lives: if a setting's status meets/exceeds promote_upcoming_changes_on_status, the resolved value is true even if the DB default is false. Permanent settings always resolve to true (admins can't disable them).enabled_for_user?(setting_name, user) — The primary access check. Considers: resolved value, group restrictions, anonymous users (only get access if no group restrictions).stats_for_user(user:, acting_guardian:) — Returns per-change status for a user including why they have/don't have access (the user_enabled_reasons enum).current_statuses / permanent_upcoming_changes — Cached lookups keyed by git version (one-time cost per deploy). Cleared by clear_caches! and automatically when TrackStatusChanges detects changes.UpcomingChanges::ConditionalDisplay (defined inside lib/upcoming_changes.rb) — Hides individual upcoming changes from the admin UI when they don't make sense in the current context (e.g. a Horizon-related change on a site without Horizon installed). Define a should_display_<upcoming_change_name>? class method on it to gate a specific change; if no method is defined, the change is always displayed. See Conditional Display below.
app/models/upcoming_change_event.rb — Audit trail. Every lifecycle event (added, removed, status change, manual toggle, admin notification) is recorded here. Has unique indexes to prevent duplicate events of specific types per change.
lib/site_setting_extension.rb — Where upcoming_change: metadata in site_settings.yml gets parsed. When a setting is registered with this metadata, it stores the parsed result in @upcoming_change_metadata and defines a {name}_groups_map method. The impact string is split into impact_type and impact_role. Also handles upcoming_change_default_override: metadata — see Default Overrides below.
lib/site_settings/defaults_provider.rb — Manages the default values for all settings, including upcoming change default overrides. Tracks which overrides are active via @active_upcoming_change_overrides and applies them when resolving defaults. Provides upcoming_change_override_metadata for the frontend to display warnings about changed defaults.
app/models/site_setting_group.rb — Stores group restrictions for settings. Group IDs are pipe-separated strings ("1|2|3"). The setting_group_ids class method returns a hash used for in-memory caching.
All services use Service::Base. They're organized under app/services/upcoming_changes/:
| Service | Purpose |
|---|---|
List | Admin-only, fetches all changes with metadata, group data, and images. Filters out changes whose ConditionalDisplay.should_display? returns false. |
Toggle | Admin enable/disable — updates SiteSetting, clears groups when neither staff nor specific_groups is in allow_enabled_for, validates the requested target against allow_enabled_for, logs staff action, fires DiscourseEvent |
Track | Orchestrator called by CheckUpcomingChanges — delegates to three action sub-services. Does not notify admins about available changes — that happens once a week in Jobs::NotifyAdminsOfAvailableUpcomingChanges. |
TrackAddedChanges | Compares current settings against event history, creates added events |
TrackRemovedChanges | Creates removed events for settings no longer present |
TrackStatusChanges | Detects status changes in metadata, creates events, clears caches |
NotifyPromotions | Iterates all changes and calls NotifyPromotion for each |
NotifyPromotion | Handles one promotion — checks policies, merges notifications, fires events |
NotificationDataMerger | Consolidates multiple change notifications into one to avoid spam (used by both the weekly availability job and NotifyPromotion) |
SiteSetting::UpsertGroups — Manages group assignments for settings (upserts SiteSettingGroup, refreshes caches, notifies clients).
app/jobs/scheduled/check_upcoming_changes.rb — Runs every 20 minutes inside a DistributedMutex. Calls Track (to log added/removed/status_changed events) then NotifyPromotions (which sends auto-promotion notifications immediately). Supports verbose logging via the upcoming_change_verbose_logging setting. Does not send "change available" notifications to admins — that is the weekly job below.
app/jobs/scheduled/notify_admins_of_available_upcoming_changes.rb — Runs once a week. Collects every change that was either added at, or status-changed to, promote_upcoming_changes_on_status - 1 within the last week and has no prior admins_notified_available_change or admins_notified_automatic_promotion event. Notifies all admins who have enable_upcoming_change_available_notifications enabled, consolidating into a single notification per admin via NotificationDataMerger (merging with existing unread notifications if present, otherwise creating one new notification per admin covering all newly-available changes). Gated on UpcomingChanges.should_notify_admins? so new sites are suppressed. Writes admins_notified_available_change events and a log_upcoming_change_available staff log entry per change.
Admin page — admin/templates/admin-config/upcoming-changes.gjs renders the page header, admin/components/admin-config-areas/upcoming-changes.gjs is the container with filtering, and admin/components/admin-config-areas/upcoming-change-item.gjs renders each row.
Key frontend patterns:
AdminFilterControlsSite 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 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 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.
Sidebar — Badge notification dot appears on the upcoming changes link when currentUser.hasNewUpcomingChanges is true.
MessageBus — Subscribes to /client_settings and updates both siteSettings and currentUserUpcomingChanges in real time.
admin/config/upcoming_changes_controller.rb — Three endpoints:
GET index — List changes (with filter_statuses param)PUT update_groups — Set group restrictions for a settingPUT toggle_change — Enable/disable a settingapp/services/problem_check/upcoming_change_stable_opted_out.rb — Warns admins hourly if they've opted out of a stable/permanent change.
Upcoming changes can override the default value of a different site setting when enabled. This allows feature rollouts to change related setting defaults without breaking admin customizations.
A setting declares a default override with the upcoming_change_default_override key in config/site_settings.yml:
# The upcoming change setting (the "trigger")
increase_suggested_topics_max_days_old_default:
default: false
type: bool
upcoming_change:
status: experimental
impact: "site_setting_default,all_members"
# The setting whose default changes (the "target")
suggested_topics_max_days_old:
default: 365
type: integer
upcoming_change_default_override:
upcoming_change: increase_suggested_topics_max_days_old_default
new_default: 1000
When increase_suggested_topics_max_days_old_default is enabled (either manually by admin or via auto-promotion), the default value of suggested_topics_max_days_old changes from 365 to 1000. The impact field on the trigger setting should include site_setting_default as its impact_type.
Registration — lib/site_setting_extension.rb parses upcoming_change_default_override during setting registration and stores it in upcoming_change_default_overrides (a hash keyed by setting name).
Activation — During SiteSetting.refresh!, each override is checked: if UpcomingChanges.enabled?(override[:upcoming_change]) returns true, the override is activated via defaults.activate_upcoming_change_override. The setting's current value is updated to new_default only if the admin has not manually modified it.
Default resolution — DefaultsProvider#all applies active overrides when resolving defaults, so code reading SiteSetting.defaults[:setting_name] gets the overridden value.
Frontend display — DefaultsProvider#upcoming_change_override_metadata returns { old_default:, new_default:, change_setting_name: } for active overrides. The site settings UI (admin/components/site-setting.gjs) shows a warning linking to the upcoming changes page.
Some upcoming changes only make sense to show admins under certain conditions — for example, a Horizon-themed change is irrelevant if Horizon isn't installed, or a change might only apply when another setting is enabled. UpcomingChanges::ConditionalDisplay (in lib/upcoming_changes.rb) lets the framework hide a change from the admin UI without removing it from site_settings.yml.
UpcomingChanges::List#fetch_upcoming_changes calls UpcomingChanges::ConditionalDisplay.should_display?(setting_name) on every change after the status filter, before group/image enrichment. Changes that return false are dropped from the result entirely.should_display? checks for a class method named should_display_<upcoming_change_name>? on ConditionalDisplay. If defined, its return value is used; otherwise the change is always displayed (returns true).ConditionalDisplay class, typically next to (or inside) the relevant subsystem's code — e.g. a Horizon-specific gate can live with the Horizon code as long as UpcomingChanges::ConditionalDisplay is reopened to define it. Group related gates together for discoverability.enabled? / enabled_for_user? still resolve normally — code paths gated on the change continue to work.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.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.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.
enable_your_feature_name:
default: false
client: true
hidden: true
upcoming_change:
status: experimental
impact: feature,all_members
body_class: true
lib/site_setting_extension.rb reads body_class from the upcoming_change: metadata and stores it (defaulting to nil/falsey) in upcoming_change_metadata.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.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.body_class (or setting it false) means no body class — the default. Add it only when you actually have CSS keyed on uc-{name}.currentUserUpcomingChanges), not globally. Anonymous/ineligible users won't get it.body_class is in the integrity spec's allowed_keys and must be a boolean — see Mocking Metadata for how to set it in tests.The current_statuses and permanent_upcoming_changes caches are keyed by git version (Discourse.git_version). This means they're naturally invalidated on every deploy — no TTL needed. Within a deploy, TrackStatusChanges calls clear_caches! when it detects metadata changes. Always call clear_caches! in tests after modifying metadata.
The resolved_value method is the single source of truth for whether a setting is "on." Auto-promotion happens implicitly: when a setting's status meets the threshold, resolved_value returns true regardless of the DB value. The DB value only changes when an admin explicitly toggles. This separation means promotion is reversible by the admin without losing the original opt-in/opt-out state.
When multiple changes need notifications, NotificationDataMerger consolidates them into a single notification per admin. It finds existing unread notifications and merges the change names array. The frontend notification types handle singular ("Feature X"), dual ("Feature X and Feature Y"), and many ("Feature X and 2 others") display.
For "change available" notifications specifically, merging also happens across the batch processed by the weekly NotifyAdminsOfAvailableUpcomingChanges job — for admins without an existing unread notification, the job builds a single new notification per admin that lists every newly-available change in that run, rather than emitting one notification per change.
Notifications for "change available" and "promoted" are skipped on new sites (determined by Migration::Helpers.new_site? in lib/migration/helpers.rb — a site is "new" if its first schema migration was less than 1 hour ago). Both the weekly NotifyAdminsOfAvailableUpcomingChanges job and the NotifyPromotion service guard on UpcomingChanges.should_notify_admins?. This prevents freshly provisioned sites from being flooded with notifications for every existing upcoming change on their first run. The tracking/detection steps still execute — only the notification delivery is suppressed.
Group restrictions use a separate SiteSettingGroup model rather than storing groups on the setting itself. This allows the caching layer (site_setting_group_ids) to work independently. Group IDs are pipe-separated in the DB for efficient single-row storage.
The allow_enabled_for metadata key on an upcoming change restricts which "Enabled for" dropdown options the admin sees. It accepts an array of any subset of [everyone, staff, specific_groups]; the No one option is always present and cannot be removed. When the key is omitted, all four options are shown (the permissive default). Rule: if everyone is present it must be the only value — everyone cannot combine with staff or specific_groups. The integrity spec enforces these rules. Server-side enforcement lives in UpcomingChanges::Toggle (validates the target when no groups are configured) and SiteSetting::UpsertGroups (validates group selection: a [staff]-only selection needs staff allowed; any other selection needs specific_groups allowed). When neither staff nor specific_groups is in the allow list, Toggle also clears any stale SiteSettingGroup records.
Auto-promoted display: When allow_enabled_for excludes :everyone and a change is enabled without an explicit admin selection (typically because it reached the promotion threshold), enabled_for_with_groups returns the broadest allowed display target — the staff group name if :staff is permitted, otherwise "groups". This is display-only; enabled_for_user? is unchanged and still treats the change as on for all users until the admin scopes it via the dropdown.
UpcomingChangeEvent has unique indexes on specific event type + change name combinations. This prevents duplicate added, removed, or notification events even if the job runs multiple times. Always check for existing events before creating new ones in service code.
UpcomingChanges.statuses in lib/upcoming_changes.rbmeets_or_exceeds_status? uses these valuesprevious_status mapping if the new status fits in the progressionapp/assets/stylesheets/admin/upcoming-changes.scss (.upcoming-change__badge.--status-{name})UpcomingChangeEvent (app/models/upcoming_change_event.rb)The three main components to know:
upcoming-changes.gjs) — Filtering logic and data managementupcoming-change-item.gjs) — Individual change row rendering and interactionsadmin-user-upcoming-changes.gjs) — Read-only per-user viewState is managed via trackedObject for reactivity. API calls go through ajax() directly in the item component.
To constrain which dropdown options an admin can pick for a change, add allow_enabled_for to its upcoming_change: metadata:
my_upcoming_change_setting:
default: false
client: true
hidden: true
upcoming_change:
status: experimental
impact: feature,all_members
allow_enabled_for:
- staff
- specific_groups
Valid value sets:
allow_enabled_for | Dropdown options shown |
|---|---|
| (omitted) | No one, Everyone, Staff, Specific group(s) |
[everyone] | No one, Everyone |
[staff] | No one, Staff |
[specific_groups] | No one, Specific group(s) |
[staff, specific_groups] | No one, Staff, Specific group(s) |
everyone cannot be combined with staff or specific_groups — when present, it must be the only value. No one is always available. The integrity spec rejects invalid combinations.
To hide an upcoming change from the admin UI under certain conditions:
UpcomingChanges::ConditionalDisplay and define a class method named should_display_<upcoming_change_name>? that returns a boolean:
module UpcomingChanges
class ConditionalDisplay
def self.should_display_enable_horizon_blah?
Discourse.plugins_by_name["horizon"].present?
end
end
end
List calls should_display? once per change.should_display? finds the method dynamically via respond_to?.To make an upcoming change control the default of another setting:
upcoming_change_default_override metadata to the target setting in config/site_settings.yml:
target_setting:
default: original_value
upcoming_change_default_override:
upcoming_change: trigger_setting_name
new_default: new_value
impact: "site_setting_default,..." in its upcoming_change: metadatamock_upcoming_change_default_overrides — see Mocking Default OverridesAll value resolution goes through resolved_value in lib/upcoming_changes.rb. If you need to change how settings are evaluated (e.g., adding a new override condition), this is the single place to modify. The method checks in order: permanent status, admin manual override, auto-promotion threshold.
Use the test helper to mock upcoming change metadata — never modify site_settings.yml in tests:
mock_upcoming_change_metadata(
{
enable_some_feature: {
impact: "feature,all_members",
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.
Use mock_upcoming_change_default_overrides to set up override metadata in tests — never modify site_settings.yml:
mock_upcoming_change_default_overrides(
{
suggested_topics_max_days_old: {
upcoming_change: :increase_suggested_topics_max_days_old_default,
new_default: 1000,
},
},
)
# Enable the trigger setting and refresh to activate the override
SiteSetting.increase_suggested_topics_max_days_old_default = true
SiteSetting.refresh!
# Now SiteSetting.suggested_topics_max_days_old returns 1000 (the overridden default)
To test that the override does NOT apply when the admin has customized the target setting:
# Admin sets a custom value before the override activates
SiteSetting.suggested_topics_max_days_old = 730
SiteSetting.increase_suggested_topics_max_days_old_default = true
SiteSetting.refresh!
# Override is not applied — admin's explicit choice is preserved
expect(SiteSetting.suggested_topics_max_days_old).to eq(730)
Stub the predicate method directly on UpcomingChanges::ConditionalDisplay rather than redefining it — this avoids leaking method definitions across examples:
UpcomingChanges::ConditionalDisplay
.stubs(:should_display_enable_upload_debug_mode?)
.returns(false)
For unit tests of ConditionalDisplay itself (where you need to verify dispatch), use define_singleton_method in before and remove_method in after to clean up:
before do
UpcomingChanges::ConditionalDisplay.define_singleton_method(
:should_display_enable_upload_debug_mode?,
) { false }
end
after do
UpcomingChanges::ConditionalDisplay.singleton_class.send(
:remove_method,
:should_display_enable_upload_debug_mode?,
)
end
When testing UpcomingChanges::List, assert the change is/isn't present in result.upcoming_changes by :setting key.
After modifying metadata or settings, call UpcomingChanges.clear_caches! to ensure tests see fresh data. The caches are keyed by git version, so they persist across test examples unless explicitly cleared.
Services follow standard Service::Base test patterns — see the discourse-service-authoring skill. Use run_successfully, fail_a_policy, etc.
Page objects live at:
spec/system/page_objects/pages/admin_upcoming_changes.rb — Main pagespec/system/page_objects/pages/admin_upcoming_change_item.rb — Item componentKey page object methods:
change_item(setting_name) — Get an item component by setting namehas_change? / has_no_change? — Visibility assertionsselect_enabled_for(option) — Toggle the enabled dropdownadd_group / remove_group / save_groups — Group managementhas_enabled_for_success_toast? — Verify success feedbackSystem tests use mock_upcoming_change_metadata in before blocks. When revisiting pages to verify persistence, be aware of rate limiting on API calls.
Use track_log_messages to verify job output:
track_log_messages do |logger|
described_class.new.execute({})
expect(logger.infos.join("\n")).to include("Expected message")
end
Set up event history with UpcomingChangeEvent.create! and clean up with delete_all as needed.
Cache isolation tests live in spec/multisite/upcoming_changes_spec.rb. Use test_multisite_connection("default") / test_multisite_connection("second") blocks and clean up cache keys explicitly per site.
Notification type tests create notifications with Notification.create() and verify director.description, director.linkHref, and director.icon. Test singular, dual, and many-change scenarios plus backward compatibility with old data formats.
| Area | Key Files |
|---|---|
| Core module | lib/upcoming_changes.rb |
| 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 |
| Controller | admin/config/upcoming_changes_controller.rb |
| Scheduled jobs | app/jobs/scheduled/check_upcoming_changes.rb, app/jobs/scheduled/notify_admins_of_available_upcoming_changes.rb |
| Problem check | app/services/problem_check/upcoming_change_stable_opted_out.rb |
| Initializer | config/initializers/015-track-upcoming-change-toggle.rb |
| Admin page | admin/templates/admin-config/upcoming-changes.gjs |
| Admin container | admin/components/admin-config-areas/upcoming-changes.gjs |
| Admin item | admin/components/admin-config-areas/upcoming-change-item.gjs |
| User view | admin/components/admin-user-upcoming-changes.gjs |
| Site settings svc | frontend/discourse/app/services/site-settings.js |
| App controller | frontend/discourse/app/controllers/application.js |
| Notifications | frontend/discourse/app/lib/notification-types/upcoming-change-*.js |
| Sidebar | frontend/discourse/app/lib/sidebar/admin-sidebar.js |
| 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 |
| Job specs | spec/jobs/scheduled/check_upcoming_changes_spec.rb, spec/jobs/scheduled/notify_admins_of_available_upcoming_changes_spec.rb |
| Multisite spec | spec/multisite/upcoming_changes_spec.rb |
| Page objects | spec/system/page_objects/pages/admin_upcoming_changes.rb, admin_upcoming_change_item.rb |
| Test helpers | spec/support/helpers.rb (search for mock_upcoming_change_metadata) |
Use when adding a new upcoming change feature flag to Discourse - handles site settings, translations, images, and code access patterns
Write HTML and CSS/SCSS for Discourse core, plugins, themes, and theme components. Use when authoring or modifying templates (.gjs/.hbs), stylesheets (.scss), component markup, or class names. Covers Discourse's BEM-with-standalone-modifiers naming, the CSS custom-property color palette (theming + dark mode), template/HTML conventions, and where stylesheets live.
Write and structure RSpec tests for Discourse core, plugins, themes, or theme components. Use when creating or modifying model specs, controller specs, service specs, job specs, system tests, or integration tests. Covers fabricators, page objects, test structure, and theme test setup.
Write and structure JavaScript/QUnit tests for Discourse core, plugins, and themes. Use when creating or modifying unit tests (lib/utility/service/model), component rendering tests, integration tests, or acceptance tests. Covers module naming, setupTest/setupRenderingTest/setupApplicationTest, fixtures, the qunit-helpers toolbox, pretender, and qunit-dom assertions.
MUST load before writing or reviewing any database migration (db/migrate, db/post_migrate, plugin migrations)
Capture screenshots of the local Discourse site across the two core themes (Foundation, Horizon) and color modes (light, dark). Use when the user asks for "screenshots of themes", "light/dark mode shots", or similar.