Skip to content

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.md
index 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 setting
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.
+### 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 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.
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.rb
index 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.rb
similarity index 55%
rename from app/services/upcoming_changes/action/track_added_changes.rb
rename to app/services/upcoming_changes/action/track_notify_added_changes.rb
index 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 bots
option :all_admins
@@ -19,6 +19,10 @@ class UpcomingChanges::Action::TrackAddedChanges < Service::ActionBase
added_changes << change_name
UpcomingChangeEvent.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 notified
end
end
diff --git a/app/services/upcoming_changes/action/track_status_changes.rb b/app/services/upcoming_changes/action/track_notify_status_changes.rb
similarity index 90%
rename from app/services/upcoming_changes/action/track_status_changes.rb
rename to app/services/upcoming_changes/action/track_notify_status_changes.rb
index 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 bots
option :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?)
end
end
diff --git a/app/services/upcoming_changes/notify_promotion.rb b/app/services/upcoming_changes/notify_promotion.rb
index 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::NotifyPromotion
policy :meets_or_exceeds_status
policy :change_has_not_already_been_notified_about_promotion
policy :admin_has_not_manually_toggled
+ policy :site_is_not_new
try do
step :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.rb
index f0173887c6b..da92fbc778e 100644
--- a/app/services/upcoming_changes/track.rb
+++ b/app/services/upcoming_changes/track.rb
@@ -21,7 +21,7 @@ class UpcomingChanges::Track
end
def 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::Track
def 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.rb
index 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_statuses
Discourse
diff --git a/spec/services/upcoming_changes/action/track_added_changes_spec.rb b/spec/services/upcoming_changes/action/track_notify_added_changes_spec.rb
similarity index 78%
rename from spec/services/upcoming_changes/action/track_added_changes_spec.rb
rename to spec/services/upcoming_changes/action/track_notify_added_changes_spec.rb
index 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 do
let(: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
+ end
end
context "when the change status does not meet promotion_status - 1" do
@@ -112,11 +131,21 @@ RSpec.describe UpcomingChanges::Action::TrackAddedChanges do
before { 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
+ }
end
it "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,
+ )
end
end
diff --git a/spec/services/upcoming_changes/action/track_status_changes_spec.rb b/spec/services/upcoming_changes/action/track_notify_status_changes_spec.rb
similarity index 94%
rename from spec/services/upcoming_changes/action/track_status_changes_spec.rb
rename to spec/services/upcoming_changes/action/track_notify_status_changes_spec.rb
index 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 do
let(: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" do
before do
UpcomingChangeEvent.create!(
diff --git a/spec/services/upcoming_changes/notify_promotion_spec.rb b/spec/services/upcoming_changes/notify_promotion_spec.rb
index 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 do
let(: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 = :stable
mock_upcoming_change_metadata(
enable_upload_debug_mode: {
@@ -74,6 +76,12 @@ RSpec.describe UpcomingChanges::NotifyPromotion do
it { 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" do
let(:notification) do
Notification.where("data::text LIKE ?", "%enable_upload_debug_mode%").last
diff --git a/spec/services/upcoming_changes/track_spec.rb b/spec/services/upcoming_changes/track_spec.rb
index 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 do
end
before 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 do
expect(result).to run_successfully
end
- it "calls TrackAddedChanges with correct arguments" do
+ it "calls TrackNotifyAddedChanges with correct arguments" do
result
- expect(UpcomingChanges::Action::TrackAddedChanges).to have_received(:call).with(all_admins:)
+ expect(UpcomingChanges::Action::TrackNotifyAddedChanges).to have_received(:call).with(
+ all_admins:,
+ )
end
it "calls TrackRemovedChanges" do
@@ -45,9 +47,9 @@ RSpec.describe UpcomingChanges::Track do
expect(UpcomingChanges::Action::TrackRemovedChanges).to have_received(:call)
end
- it "calls TrackStatusChanges with correct arguments" do
+ it "calls TrackNotifyStatusChanges with correct arguments" do
result
- 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],