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.mdindex 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 EnabledA 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 stablehide_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.mdindex 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 TranslationAdd to `config/locales/server.en.yml` under `site_settings:`:diff --git a/config/site_settings.yml b/config/site_settings.ymlindex 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: falseklipy_api_key:default: ""secret: true@@ -2091,6 +2096,7 @@ email:allow_enabled_for:- everyonelearn_more_url: "https://meta.discourse.org/t/-/395927"+ permanent_warning: falsereply_by_email_enabled:default: falsevalidator: "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: falseallow_enabled_for:- everyoneexperimental_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: falseallow_enabled_for:- everyonegranular_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.gjsindex 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.gjsindex 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.rbindex 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 SiteSettingExtensionstatus: 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,)enddiff --git a/plugins/discourse-reactions/config/settings.yml b/plugins/discourse-reactions/config/settings.ymlindex 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: falseenable_new_post_reply_count_position:default: falseclient: truediff --git a/spec/integrity/upcoming_change_metadata_spec.rb b/spec/integrity/upcoming_change_metadata_spec.rbindex 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" doit "#{label} is valid" dometadata = 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_keysmissing_keys = required_keys - metadata.keys@@ -56,6 +64,7 @@ RSpec.describe "upcoming change metadata integrity checks" dolearn_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.rbindex 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" doexpect(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" domock_upcoming_change_metadata({about_page_extra_groups_show_description: {@@ -76,6 +76,7 @@ describe "Admin upcoming changes" dostatus: :stable,impact_type: "site_setting_default",impact_role: "all_members",+ permanent_warning: false,},},)