A platform for community discussion. Free, open, simple.
FIX: Do not notify admins of upcoming changes on new sites (#38890)
Martin Brennanc6d8fcf95f94
diff --git a/.skills/discourse-upcoming-changes-authoring/SKILL.md b/.skills/discourse-upcoming-changes-authoring/SKILL.mdindex 14de2f30cbb..89b8b48b0ac 100644--- a/.skills/discourse-upcoming-changes-authoring/SKILL.md+++ b/.skills/discourse-upcoming-changes-authoring/SKILL.md@@ -20,7 +20,7 @@ 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.+- `current_statuses` / `permanent_upcoming_changes` — Cached lookups keyed by git version (one-time cost per deploy). Cleared by `clear_caches!` and automatically when `TrackNotifyStatusChanges` 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.@@ -37,9 +37,9 @@ All services use `Service::Base`. They're organized under `app/services/upcoming| `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 |+| `TrackNotifyAddedChanges` | 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 |+| `TrackNotifyStatusChanges` | 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 |@@ -86,7 +86,7 @@ All services use `Service::Base`. They're organized under `app/services/upcoming### 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.+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, `TrackNotifyStatusChanges` calls `clear_caches!` when it detects metadata changes. Always call `clear_caches!` in tests after modifying metadata.### Auto-Promotion@@ -96,6 +96,10 @@ The `resolved_value` method is the single source of truth for whether a settingWhen 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.+### New Site Notification Suppression++Notifications for `added` and `promoted` changes 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). 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-Based AccessGroup 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.diff --git a/app/services/upcoming_changes/action/notify_admins_of_available_change.rb b/app/services/upcoming_changes/action/notify_admins_of_available_change.rbindex 99f3f958b94..160e88fcc97 100644--- a/app/services/upcoming_changes/action/notify_admins_of_available_change.rb+++ b/app/services/upcoming_changes/action/notify_admins_of_available_change.rb@@ -1,7 +1,7 @@# frozen_string_literal: true-# Intended to be called from UpcomingChanges::Action::TrackStatusChanges, and-# UpcomingChanges::Action::TrackAddedChanges, not standalone.+# Intended to be called from UpcomingChanges::Action::TrackNotifyStatusChanges, and+# UpcomingChanges::Action::TrackNotifyAddedChanges, not standalone.## Send a notification to all admins that the upcoming change is available for# them to opt-in to.diff --git a/app/services/upcoming_changes/action/track_added_changes.rb b/app/services/upcoming_changes/action/track_notify_added_changes.rbsimilarity index 55%rename from app/services/upcoming_changes/action/track_added_changes.rbrename to app/services/upcoming_changes/action/track_notify_added_changes.rbindex 5ab9c1dd6ad..07e10b4de36 100644--- a/app/services/upcoming_changes/action/track_added_changes.rb+++ b/app/services/upcoming_changes/action/track_notify_added_changes.rb@@ -7,7 +7,7 @@# * Compare with SiteSetting.upcoming_change_site_settings to see if there are any missing# * If so, create an `added` event for the added changes# * Send notifications to all admins if the change is the correct status (promotion_status - 1)-class UpcomingChanges::Action::TrackAddedChanges < Service::ActionBase+class UpcomingChanges::Action::TrackNotifyAddedChanges < Service::ActionBase# Every admin user that are not botsoption :all_admins@@ -19,6 +19,10 @@ class UpcomingChanges::Action::TrackAddedChanges < Service::ActionBaseadded_changes << change_nameUpcomingChangeEvent.create!(event_type: :added, upcoming_change_name: change_name)+ # No point in notifying admins on brand new sites, the upcoming change system+ # is more about notifying admins of changes to established sites.+ next if Migration::Helpers.new_site? && !Rails.env.development?+# We only want to notify admins once the change has reached a certain status,# which is the promotion status minus one (previous status).#@@ -26,25 +30,24 @@ class UpcomingChanges::Action::TrackAddedChanges < Service::ActionBase# send a notification to admins that the UC is available in a later deploy.notify_at_status =UpcomingChanges.previous_status(SiteSetting.promote_upcoming_changes_on_status)+ next if !UpcomingChanges.meets_or_exceeds_status?(change_name, notify_at_status)- if UpcomingChanges.meets_or_exceeds_status?(change_name, notify_at_status)- # However, we want to skip notifying if the change already meets the- # promotion status criteria. The UpcomingChanges::Promote service will- # handle it instead.- #- # We don't want to notify admins that a change is available then- # immediately notify them it's enabled.- if !UpcomingChanges.meets_or_exceeds_status?(- change_name,- SiteSetting.promote_upcoming_changes_on_status.to_sym,- )- Rails.logger.info(- "Notifying admins about available change #{change_name} from TrackAddedChanges",- )- notified =- UpcomingChanges::Action::NotifyAdminsOfAvailableChange.call(change_name:, all_admins:)- notified_changes << change_name if notified- end+ # However, we want to skip notifying if the change already meets the+ # promotion status criteria. The UpcomingChanges::Promote service will+ # handle it instead.+ #+ # We don't want to notify admins that a change is available then+ # immediately notify them it's enabled.+ if !UpcomingChanges.meets_or_exceeds_status?(+ change_name,+ SiteSetting.promote_upcoming_changes_on_status.to_sym,+ )+ Rails.logger.info(+ "Notifying admins about available change #{change_name} from TrackNotifyAddedChanges",+ )+ notified =+ UpcomingChanges::Action::NotifyAdminsOfAvailableChange.call(change_name:, all_admins:)+ notified_changes << change_name if notifiedendenddiff --git a/app/services/upcoming_changes/action/track_status_changes.rb b/app/services/upcoming_changes/action/track_notify_status_changes.rbsimilarity index 90%rename from app/services/upcoming_changes/action/track_status_changes.rbrename to app/services/upcoming_changes/action/track_notify_status_changes.rbindex 030ce801609..b8461f78adf 100644--- a/app/services/upcoming_changes/action/track_status_changes.rb+++ b/app/services/upcoming_changes/action/track_notify_status_changes.rb@@ -10,7 +10,7 @@# then don't send another notification# * If the change was not added, send a notification about the status change if it's the correct# status (promotion_status - 1) to indicate it's available to admins-class UpcomingChanges::Action::TrackStatusChanges < Service::ActionBase+class UpcomingChanges::Action::TrackNotifyStatusChanges < Service::ActionBase# Every admin user that are not botsoption :all_admins@@ -67,13 +67,17 @@ class UpcomingChanges::Action::TrackStatusChanges < Service::ActionBase# However, if the status was later changed and it meets the promotion status# minus one (previous status) criteria for notification, then we should notify# admins here.+ #+ # Note that on new sites (< 1 hour old), we don't notify admins about added+ # changes, since the upcoming change system is more about notifying admins of+ # changes to established sites.if should_notify_admins?(change_name) &&!UpcomingChanges.meets_or_exceeds_status?(change_name,SiteSetting.promote_upcoming_changes_on_status.to_sym,)Rails.logger.info(- "Notifying admins about available change #{change_name} from TrackStatusChanges",+ "Notifying admins about available change #{change_name} from TrackNotifyStatusChanges",)notified =UpcomingChanges::Action::NotifyAdminsOfAvailableChange.call(change_name:, all_admins:)@@ -114,6 +118,6 @@ class UpcomingChanges::Action::TrackStatusChanges < Service::ActionBase!UpcomingChangeEvent.exists?(upcoming_change_name: change_name,event_type: :admins_notified_available_change,- )+ ) && (!Migration::Helpers.new_site? && !Rails.env.development?)endenddiff --git a/app/services/upcoming_changes/notify_promotion.rb b/app/services/upcoming_changes/notify_promotion.rbindex c37d978d19f..86eb258fa7e 100644--- a/app/services/upcoming_changes/notify_promotion.rb+++ b/app/services/upcoming_changes/notify_promotion.rb@@ -29,6 +29,7 @@ class UpcomingChanges::NotifyPromotionpolicy :meets_or_exceeds_statuspolicy :change_has_not_already_been_notified_about_promotionpolicy :admin_has_not_manually_toggled+ policy :site_is_not_newtry dostep :log_promotion@@ -60,6 +61,10 @@ class UpcomingChanges::NotifyPromotion!SiteSetting.modified.key?(params.setting_name)end+ def site_is_not_new(params:)+ !Migration::Helpers.new_site? && !Rails.env.development?+ end+def log_promotion(params:, guardian:)context =I18n.t(diff --git a/app/services/upcoming_changes/track.rb b/app/services/upcoming_changes/track.rbindex f0173887c6b..da92fbc778e 100644--- a/app/services/upcoming_changes/track.rb+++ b/app/services/upcoming_changes/track.rb@@ -21,7 +21,7 @@ class UpcomingChanges::Trackenddef fetch_added_changes(all_admins:)- result = UpcomingChanges::Action::TrackAddedChanges.call(all_admins:)+ result = UpcomingChanges::Action::TrackNotifyAddedChanges.call(all_admins:)context[:notified_admins_for_added_changes] = result[:notified_changes]result[:added_changes]end@@ -32,7 +32,7 @@ class UpcomingChanges::Trackdef fetch_status_changes(added_changes:, removed_changes:, all_admins:)result =- UpcomingChanges::Action::TrackStatusChanges.call(+ UpcomingChanges::Action::TrackNotifyStatusChanges.call(all_admins:,added_changes:,removed_changes:,diff --git a/lib/upcoming_changes.rb b/lib/upcoming_changes.rbindex 4c52c9061ee..9189bfa5ebd 100644--- a/lib/upcoming_changes.rb+++ b/lib/upcoming_changes.rb@@ -285,7 +285,7 @@ module UpcomingChanges# to save time in other places in the codebase when we have to figure out# when an upcoming change moved to its current status.#- # This cache is automatically cleared when UpcomingChanges::Action::TrackStatusChanges+ # This cache is automatically cleared when UpcomingChanges::Action::TrackNotifyStatusChanges# is called, since that adds new UpcomingChangeEvent records.def self.current_statusesDiscoursediff --git a/spec/services/upcoming_changes/action/track_added_changes_spec.rb b/spec/services/upcoming_changes/action/track_notify_added_changes_spec.rbsimilarity index 78%rename from spec/services/upcoming_changes/action/track_added_changes_spec.rbrename to spec/services/upcoming_changes/action/track_notify_added_changes_spec.rbindex 632fd2e6c3a..0d8962ccae4 100644--- a/spec/services/upcoming_changes/action/track_added_changes_spec.rb+++ b/spec/services/upcoming_changes/action/track_notify_added_changes_spec.rb@@ -1,10 +1,12 @@# frozen_string_literal: true-RSpec.describe UpcomingChanges::Action::TrackAddedChanges do+RSpec.describe UpcomingChanges::Action::TrackNotifyAddedChanges dolet(:enable_upload_debug_mode_status) { :experimental }let(:show_user_menu_avatars_status) { :beta }before do+ # No upcoming change notifications are sent for new sites+ Migration::Helpers.stubs(:new_site?).returns(false)mock_upcoming_change_metadata({enable_upload_debug_mode: {@@ -103,6 +105,23 @@ RSpec.describe UpcomingChanges::Action::TrackAddedChanges do).count}.by(1)end++ context "when the site is new (< 1 hour old)" do+ before { Migration::Helpers.stubs(:new_site?).returns(true) }++ it "does not notify admins that a change is available" do+ expect { result }.not_to change { Notification.count }+ end++ it "does still make the upcoming change event" do+ expect { result }.to change {+ scoped_events.where(+ event_type: :added,+ upcoming_change_name: :show_user_menu_avatars,+ ).count+ }.by(1)+ end+ endendcontext "when the change status does not meet promotion_status - 1" do@@ -112,11 +131,21 @@ RSpec.describe UpcomingChanges::Action::TrackAddedChanges dobefore { SiteSetting.promote_upcoming_changes_on_status = "stable" }it "does not notify admins for the scoped alpha changes" do- expect { result }.not_to change { Notification.count }+ expect { result }.not_to change {+ Notification+ .where(notification_type: Notification.types[:upcoming_change_available])+ .where(+ "data::text LIKE '%enable_upload_debug_mode%' OR data::text LIKE '%show_user_menu_avatars%'",+ )+ .count+ }endit "does not include the scoped changes in notified_changes" do- expect(result[:notified_changes]).to be_empty+ expect(result[:notified_changes]).not_to include(+ :enable_upload_debug_mode,+ :show_user_menu_avatars,+ )endenddiff --git a/spec/services/upcoming_changes/action/track_status_changes_spec.rb b/spec/services/upcoming_changes/action/track_notify_status_changes_spec.rbsimilarity index 94%rename from spec/services/upcoming_changes/action/track_status_changes_spec.rbrename to spec/services/upcoming_changes/action/track_notify_status_changes_spec.rbindex 08901cb4a34..776f5a5516a 100644--- a/spec/services/upcoming_changes/action/track_status_changes_spec.rb+++ b/spec/services/upcoming_changes/action/track_notify_status_changes_spec.rb@@ -1,10 +1,12 @@# frozen_string_literal: true-RSpec.describe UpcomingChanges::Action::TrackStatusChanges do+RSpec.describe UpcomingChanges::Action::TrackNotifyStatusChanges dolet(:enable_upload_debug_mode_status) { :experimental }let(:show_user_menu_avatars_status) { :beta }before do+ # No upcoming change notifications are sent for new sites+ Migration::Helpers.stubs(:new_site?).returns(false)mock_upcoming_change_metadata({enable_upload_debug_mode: {@@ -292,6 +294,19 @@ RSpec.describe UpcomingChanges::Action::TrackStatusChanges do}.by(1)end+ context "when the site is new (< 1 hour old)" do+ before { Migration::Helpers.stubs(:new_site?).returns(true) }++ it "does not notify admins" do+ expect { result }.not_to change {+ Notification+ .where(notification_type: Notification.types[:upcoming_change_available])+ .where("data::text LIKE ?", "%show_user_menu_avatars%")+ .count+ }+ end+ end+context "when admins were already notified" dobefore doUpcomingChangeEvent.create!(diff --git a/spec/services/upcoming_changes/notify_promotion_spec.rb b/spec/services/upcoming_changes/notify_promotion_spec.rbindex 67b87f1b22f..a906f18790f 100644--- a/spec/services/upcoming_changes/notify_promotion_spec.rb+++ b/spec/services/upcoming_changes/notify_promotion_spec.rb@@ -27,6 +27,8 @@ RSpec.describe UpcomingChanges::NotifyPromotion dolet(:setting_status) { :stable }before do+ # No upcoming change notifications are sent for new sites+ Migration::Helpers.stubs(:new_site?).returns(false)SiteSetting.promote_upcoming_changes_on_status = :stablemock_upcoming_change_metadata(enable_upload_debug_mode: {@@ -74,6 +76,12 @@ RSpec.describe UpcomingChanges::NotifyPromotion doit { is_expected.to fail_a_policy(:admin_has_not_manually_toggled) }end+ context "when the site is new (< 1 hour old)" do+ before { Migration::Helpers.stubs(:new_site?).returns(true) }++ it { is_expected.to fail_a_policy(:site_is_not_new) }+ end+context "when everything's ok" dolet(:notification) doNotification.where("data::text LIKE ?", "%enable_upload_debug_mode%").lastdiff --git a/spec/services/upcoming_changes/track_spec.rb b/spec/services/upcoming_changes/track_spec.rbindex 0ba241161f8..d79d8a69503 100644--- a/spec/services/upcoming_changes/track_spec.rb+++ b/spec/services/upcoming_changes/track_spec.rb@@ -20,13 +20,13 @@ RSpec.describe UpcomingChanges::Track doendbefore do- allow(UpcomingChanges::Action::TrackAddedChanges).to receive(:call).and_return(+ allow(UpcomingChanges::Action::TrackNotifyAddedChanges).to receive(:call).and_return(added_changes_result,)allow(UpcomingChanges::Action::TrackRemovedChanges).to receive(:call).and_return(removed_changes_result,)- allow(UpcomingChanges::Action::TrackStatusChanges).to receive(:call).and_return(+ allow(UpcomingChanges::Action::TrackNotifyStatusChanges).to receive(:call).and_return(status_changes_result,)end@@ -35,9 +35,11 @@ RSpec.describe UpcomingChanges::Track doexpect(result).to run_successfullyend- it "calls TrackAddedChanges with correct arguments" do+ it "calls TrackNotifyAddedChanges with correct arguments" doresult- expect(UpcomingChanges::Action::TrackAddedChanges).to have_received(:call).with(all_admins:)+ expect(UpcomingChanges::Action::TrackNotifyAddedChanges).to have_received(:call).with(+ all_admins:,+ )endit "calls TrackRemovedChanges" do@@ -45,9 +47,9 @@ RSpec.describe UpcomingChanges::Track doexpect(UpcomingChanges::Action::TrackRemovedChanges).to have_received(:call)end- it "calls TrackStatusChanges with correct arguments" do+ it "calls TrackNotifyStatusChanges with correct arguments" doresult- expect(UpcomingChanges::Action::TrackStatusChanges).to have_received(:call).with(+ expect(UpcomingChanges::Action::TrackNotifyStatusChanges).to have_received(:call).with(all_admins:,added_changes: [:added_change],removed_changes: [:removed_change],