Skip to content

A platform for community discussion. Free, open, simple.

DEV: Add a skill for working on upcoming changes code (#38851)

Martin Brennan8e62ecb5319f
diff --git a/.skills/discourse-upcoming-changes-authoring/SKILL.md b/.skills/discourse-upcoming-changes-authoring/SKILL.md
new file mode 100644
index 00000000000..14de2f30cbb
--- /dev/null
+++ b/.skills/discourse-upcoming-changes-authoring/SKILL.md
@@ -0,0 +1,232 @@
+---
+name: discourse-upcoming-changes-authoring
+description: Use when modifying, debugging, or extending the upcoming changes framework code and system itself.
+---
+
+# Upcoming Changes Framework — Authoring Guide
+
+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.
+
+## Architecture Overview
+
+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.
+
+### Ruby Core
+
+**`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.
+
+**`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`.
+
+**`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.
+
+### Services Layer
+
+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 |
+| `Toggle` | Admin enable/disable — updates SiteSetting, clears groups if `disallow_enabled_for_groups`, logs staff action, fires DiscourseEvent |
+| `Track` | Orchestrator called by the scheduled job — delegates to three action sub-services |
+| `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 |
+| `NotifyAdminsOfAvailableChange` | Notifies admins when a change reaches one status below promotion threshold |
+| `NotificationDataMerger` | Consolidates multiple change notifications into one to avoid spam |
+
+**`SiteSetting::UpsertGroups`** — Manages group assignments for settings (upserts `SiteSettingGroup`, refreshes caches, notifies clients).
+
+### Scheduled Job
+
+**`app/jobs/scheduled/check_upcoming_changes.rb`** — Runs every 20 minutes inside a `DistributedMutex`. Calls `Track` then `NotifyPromotions`. Supports verbose logging via the `upcoming_change_verbose_logging` setting.
+
+### Frontend
+
+**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:**
+- Filtering by status, impact type, impact role, and enabled/disabled state via `AdminFilterControls`
+- Group selection uses a multi-select dropdown with debounced API saves
+- Toast notifications for all toggle/group changes
+- Lightbox integration for preview images
+
+**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.
+
+**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.
+
+### Controller
+
+**`admin/config/upcoming_changes_controller.rb`** — Three endpoints:
+- `GET index` — List changes (with `filter_statuses` param)
+- `PUT update_groups` — Set group restrictions for a setting
+- `PUT toggle_change` — Enable/disable a setting
+
+### Problem Check
+
+**`app/services/problem_check/upcoming_change_stable_opted_out.rb`** — Warns admins hourly if they've opted out of a stable/permanent change.
+
+## Key Design Decisions
+
+### Caching Strategy
+
+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.
+
+### Auto-Promotion
+
+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.
+
+### Notification Merging
+
+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.
+
+### Group-Based Access
+
+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. When `disallow_enabled_for_groups` is set in metadata, the UI only shows Everyone/No One options. Group IDs are pipe-separated in the DB for efficient single-row storage.
+
+### Event Idempotency
+
+`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.
+
+## Common Modification Scenarios
+
+### Adding a New Status
+
+1. Add the status and its numeric value to `UpcomingChanges.statuses` in `lib/upcoming_changes.rb`
+2. The numeric ordering determines hierarchy — `meets_or_exceeds_status?` uses these values
+3. Update `previous_status` mapping if the new status fits in the progression
+4. Add status badge styling in `app/assets/stylesheets/admin/upcoming-changes.scss` (`.upcoming-change__badge.--status-{name}`)
+5. Add translations for the status label
+
+### Adding a New Event Type
+
+1. Add the enum value to `UpcomingChangeEvent` (`app/models/upcoming_change_event.rb`)
+2. If the event should be unique per change, add a unique index in a migration
+3. Create or update the relevant service to emit the event
+
+### Modifying the Admin UI
+
+The three main components to know:
+- **Container** (`upcoming-changes.gjs`) — Filtering logic and data management
+- **Item** (`upcoming-change-item.gjs`) — Individual change row rendering and interactions
+- **User view** (`admin-user-upcoming-changes.gjs`) — Read-only per-user view
+
+State is managed via `trackedObject` for reactivity. API calls go through `ajax()` directly in the item component.
+
+### Changing Resolution Logic
+
+All 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.
+
+## Testing Patterns
+
+### Mocking Metadata
+
+Use the test helper to mock upcoming change metadata — never modify `site_settings.yml` in tests:
+
+```ruby
+mock_upcoming_change_metadata(
+ {
+ enable_some_feature: {
+ impact: "feature,all_members",
+ status: :experimental,
+ impact_type: "feature",
+ impact_role: "all_members",
+ },
+ },
+)
+```
+
+Always clean up with `clear_mocked_upcoming_change_metadata` in an `after` block (or the helper handles it automatically depending on context). The helper is defined in `spec/support/helpers.rb`.
+
+### Cache Clearing in Tests
+
+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.
+
+### Testing Services
+
+Services follow standard `Service::Base` test patterns — see the `discourse-service-authoring` skill. Use `run_successfully`, `fail_a_policy`, etc.
+
+### System Tests
+
+Page objects live at:
+- `spec/system/page_objects/pages/admin_upcoming_changes.rb` — Main page
+- `spec/system/page_objects/pages/admin_upcoming_change_item.rb` — Item component
+
+Key page object methods:
+- `change_item(setting_name)` — Get an item component by setting name
+- `has_change?` / `has_no_change?` — Visibility assertions
+- `select_enabled_for(option)` — Toggle the enabled dropdown
+- `add_group` / `remove_group` / `save_groups` — Group management
+- `has_enabled_for_success_toast?` — Verify success feedback
+
+System tests use `mock_upcoming_change_metadata` in `before` blocks. When revisiting pages to verify persistence, be aware of rate limiting on API calls.
+
+### Testing the Scheduled Job
+
+Use `track_log_messages` to verify job output:
+
+```ruby
+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.
+
+### Multisite Tests
+
+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.
+
+### JavaScript Tests
+
+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.
+
+## File Reference
+
+| 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`) |
+| Services | `app/services/upcoming_changes/*.rb` |
+| Group upsert | `app/services/site_setting/upsert_groups.rb` |
+| Controller | `admin/config/upcoming_changes_controller.rb` |
+| Scheduled job | `app/jobs/scheduled/check_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` |
+| 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 spec | `spec/jobs/scheduled/check_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`) |