Skip to content

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

DEV: add upcoming change permanent banner metadata (#41700)

David Battersbye8883f7a8f12
diff --git a/.skills/discourse-upcoming-changes-authoring/SKILL.md b/.skills/discourse-upcoming-changes-authoring/SKILL.md
index 2350309cb2c..bfc15aece7f 100644
--- a/.skills/discourse-upcoming-changes-authoring/SKILL.md
+++ b/.skills/discourse-upcoming-changes-authoring/SKILL.md
@@ -178,6 +178,33 @@ enable_your_feature_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.
+### Permanent Soon Warning
+
+Once a change reaches `stable` status, the admin page shows a warning on its row: "This change will become permanent soon. You will no longer be able to opt-out." This is **opt-out** via the `permanent_warning:` metadata key — every stable change shows the warning unless it explicitly sets `permanent_warning: false`.
+
+```yaml
+enable_your_feature_name:
+ default: false
+ client: true
+ hidden: true
+ upcoming_change:
+ status: "stable"
+ impact: "site_setting_default,all_members"
+ permanent_warning: false
+```
+
+#### How It Works
+
+1. **Parsing** — `lib/site_setting_extension.rb` reads `permanent_warning` from the `upcoming_change:` metadata and normalizes it to a boolean (`!= false`, so an omitted key becomes `true`) in `upcoming_change_metadata`.
+2. **Rendering** — `UpcomingChangeItem#showPermanentSoonNotice` (`admin/components/admin-config-areas/upcoming-change-item.gjs`) renders the notice when `status === "stable"` and `permanent_warning !== false`. The `!== false` comparison (rather than a truthy check) means metadata that omits the key — including hashes built by `mock_upcoming_change_metadata` — still shows the notice.
+
+#### Key Behaviors
+
+- **Opt-out, not opt-in**: The default is to warn. Suppress it only when the warning would be misleading — the usual case is a `site_setting_default` change, where becoming permanent just changes another setting's default and the admin can still set that setting to whatever they want.
+- **Stable-only**: The key has no effect below `stable`, and `permanent` changes don't show the notice either (they already are permanent).
+- **Independent of `impact_type`**: Before this key existed, the notice was implicitly suppressed for every `site_setting_default` change. That coupling is gone — impact type no longer affects the notice.
+- **Integrity-checked**: `permanent_warning` is in the integrity spec's `allowed_keys` and must be a boolean.
+
### Hiding Settings While Enabled
A change can declare other site settings that should be hidden from admins while it is enabled, via the optional `hide_settings:` metadata key. This is for *legacy* settings that stop making sense once the change replaces them — they disappear from the admin UI rather than being deleted, and reappear if the change is disabled.
@@ -373,6 +400,7 @@ mock_upcoming_change_metadata(
impact_type: "feature",
impact_role: "all_members",
body_class: true, # optional — opts into the uc-{name} body class
+ permanent_warning: false, # optional — suppresses the "becomes permanent soon" notice at stable
hide_settings: %i[legacy_setting_one], # optional — settings hidden while enabled
},
},
diff --git a/.skills/discourse-upcoming-changes/SKILL.md b/.skills/discourse-upcoming-changes/SKILL.md
index 5f538c0f6aa..ec4331fa8a3 100644
--- a/.skills/discourse-upcoming-changes/SKILL.md
+++ b/.skills/discourse-upcoming-changes/SKILL.md
@@ -92,6 +92,15 @@ upcoming_change:
include_css: true
```
+**Optional:** Add `permanent_warning: false` to suppress the "This change will become permanent soon. You will no longer be able to opt-out." notice that is shown on the admin page once the change reaches `stable`. The notice is shown by default for every change; opt out only when it is misleading — typically changes that just flip the default value of another site setting (`impact: "site_setting_default,..."`), which admins can always set back afterwards.
+
+```yaml
+upcoming_change:
+ status: "stable"
+ impact: "site_setting_default,all_members"
+ permanent_warning: false
+```
+
### 2. Add Translation
Add to `config/locales/server.en.yml` under `site_settings:`:
diff --git a/config/site_settings.yml b/config/site_settings.yml
index 97c130997b1..16f77637746 100644
--- a/config/site_settings.yml
+++ b/config/site_settings.yml
@@ -37,6 +37,10 @@
# - 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
+# - permanent_warning: (optional boolean, defaults to true) when the change reaches
+# `stable` status admins are warned that it will become permanent and they will no
+# longer be able to opt out. Set to false when that warning does not apply, for
+# example a change that only alters the default value of another site setting.
# - 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.
@@ -1700,6 +1704,7 @@ posting:
status: "stable"
impact: "feature,all_members"
learn_more_url: "https://meta.discourse.org/t/-/404829"
+ permanent_warning: false
klipy_api_key:
default: ""
secret: true
@@ -2091,6 +2096,7 @@ email:
allow_enabled_for:
- everyone
learn_more_url: "https://meta.discourse.org/t/-/395927"
+ permanent_warning: false
reply_by_email_enabled:
default: false
validator: "ReplyByEmailEnabledValidator"
@@ -4622,6 +4628,7 @@ experimental:
status: "permanent"
impact: "site_setting_default,all_members"
learn_more_url: "https://meta.discourse.org/t/-/397098"
+ permanent_warning: false
allow_enabled_for:
- everyone
experimental_topic_category_change_notification:
@@ -4646,6 +4653,7 @@ experimental:
status: "stable"
impact: "site_setting_default,all_members"
learn_more_url: "https://meta.discourse.org/t/-/402843"
+ permanent_warning: false
allow_enabled_for:
- everyone
granular_anonymous_and_logged_in_groups_permissions:
diff --git a/frontend/discourse/admin/components/admin-config-areas/upcoming-change-item.gjs b/frontend/discourse/admin/components/admin-config-areas/upcoming-change-item.gjs
index e565ef5b339..5998c216a08 100644
--- a/frontend/discourse/admin/components/admin-config-areas/upcoming-change-item.gjs
+++ b/frontend/discourse/admin/components/admin-config-areas/upcoming-change-item.gjs
@@ -98,7 +98,7 @@ export default class UpcomingChangeItem extends Component {
get showPermanentSoonNotice() {
return (
this.args.change.upcoming_change.status === "stable" &&
- this.args.change.upcoming_change.impact_type !== "site_setting_default"
+ this.args.change.upcoming_change.permanent_warning !== false
);
}
diff --git a/frontend/discourse/tests/integration/components/admin-config-areas/upcoming-change-item-test.gjs b/frontend/discourse/tests/integration/components/admin-config-areas/upcoming-change-item-test.gjs
index efeb71bc7aa..209c07d95c4 100644
--- a/frontend/discourse/tests/integration/components/admin-config-areas/upcoming-change-item-test.gjs
+++ b/frontend/discourse/tests/integration/components/admin-config-areas/upcoming-change-item-test.gjs
@@ -197,13 +197,14 @@ module("Integration | Component | UpcomingChangeItem", function (hooks) {
);
});
- test("does not render the permanent soon notice when impact_type is site_setting_default", async function (assert) {
+ test("does not render the permanent soon notice when permanent_warning is false", async function (assert) {
const change = buildChange({
upcoming_change: {
status: "stable",
impact: "site_setting_default,all_members",
impact_type: "site_setting_default",
impact_role: "all_members",
+ permanent_warning: false,
enabled_for: "everyone",
},
});
@@ -219,7 +220,7 @@ module("Integration | Component | UpcomingChangeItem", function (hooks) {
assert
.dom(".upcoming-change__status-notice")
.doesNotExist(
- "does not show the permanent soon notice for site setting default changes"
+ "does not show the permanent soon notice when the change opts out of it"
);
});
diff --git a/lib/site_setting_extension.rb b/lib/site_setting_extension.rb
index c5f08a14835..9a7b968351c 100644
--- a/lib/site_setting_extension.rb
+++ b/lib/site_setting_extension.rb
@@ -179,6 +179,10 @@ module SiteSettingExtension
# 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.
+ # permanent_warning: (optional) boolean, defaults to true. When the change reaches
+ # `stable` status, admins are warned in the UI that it will become permanent and
+ # they will no longer be able to opt out. Set to false for changes where that
+ # warning does not apply, e.g. changes that only alter a site setting default.
# hide_settings: (optional) array of other site setting names to hide from
# admins while this change is enabled (manual opt-in or auto-promotion).
# Use for legacy settings that stop making sense once the change is in
@@ -1349,6 +1353,7 @@ module SiteSettingExtension
status: opts[:upcoming_change][:status].to_sym,
allow_enabled_for: allow_enabled_for,
body_class: opts[:upcoming_change][:body_class],
+ permanent_warning: opts[:upcoming_change][:permanent_warning] != false,
hide_settings: hide_settings,
)
end
diff --git a/plugins/discourse-reactions/config/settings.yml b/plugins/discourse-reactions/config/settings.yml
index 3298daa8154..367d747d691 100644
--- a/plugins/discourse-reactions/config/settings.yml
+++ b/plugins/discourse-reactions/config/settings.yml
@@ -42,6 +42,7 @@ discourse_reactions:
status: "beta"
impact: "site_setting_default,all_members"
learn_more_url: "https://meta.discourse.org/t/-/403795"
+ permanent_warning: false
enable_new_post_reply_count_position:
default: false
client: true
diff --git a/spec/integrity/upcoming_change_metadata_spec.rb b/spec/integrity/upcoming_change_metadata_spec.rb
index d3653683c5c..7209703f55c 100644
--- a/spec/integrity/upcoming_change_metadata_spec.rb
+++ b/spec/integrity/upcoming_change_metadata_spec.rb
@@ -45,7 +45,15 @@ 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 body_class hide_settings]
+ allowed_keys = %i[
+ status
+ impact
+ learn_more_url
+ allow_enabled_for
+ body_class
+ permanent_warning
+ hide_settings
+ ]
required_keys = %i[status impact]
unsupported_keys = metadata.keys - allowed_keys
missing_keys = required_keys - metadata.keys
@@ -56,6 +64,7 @@ RSpec.describe "upcoming change metadata integrity checks" do
learn_more_url = metadata[:learn_more_url]
allow_enabled_for = metadata[:allow_enabled_for]
body_class = metadata[:body_class]
+ permanent_warning = metadata[:permanent_warning]
hide_settings = metadata[:hide_settings]
aggregate_failures do
@@ -117,6 +126,11 @@ RSpec.describe "upcoming change metadata integrity checks" do
"#{label} `upcoming_change.body_class` must be a boolean"
end
+ unless permanent_warning.nil?
+ expect([true, false]).to include(permanent_warning),
+ "#{label} `upcoming_change.permanent_warning` must be a boolean"
+ end
+
if hide_settings.present?
expect(hide_settings).to be_an(Array),
"#{label} `upcoming_change.hide_settings` must be an array"
diff --git a/spec/system/admin_upcoming_changes_spec.rb b/spec/system/admin_upcoming_changes_spec.rb
index a795afddfcf..e7a693cb9f9 100644
--- a/spec/system/admin_upcoming_changes_spec.rb
+++ b/spec/system/admin_upcoming_changes_spec.rb
@@ -62,7 +62,7 @@ describe "Admin upcoming changes" do
expect(upcoming_changes_page).to have_no_change(:about_page_extra_groups_show_description)
end
- it "shows the permanent soon notice for stable changes but not for site_setting_default types" do
+ it "shows the permanent soon notice for stable changes unless permanent_warning is false" do
mock_upcoming_change_metadata(
{
about_page_extra_groups_show_description: {
@@ -76,6 +76,7 @@ describe "Admin upcoming changes" do
status: :stable,
impact_type: "site_setting_default",
impact_role: "all_members",
+ permanent_warning: false,
},
},
)