A platform for community discussion. Free, open, simple.
DEV: Add plugin registry for UC conditional display (#41645)
Martin Brennan87142377608a
diff --git a/.skills/discourse-upcoming-changes-authoring/SKILL.md b/.skills/discourse-upcoming-changes-authoring/SKILL.mdindex ae9abd8bbc0..2350309cb2c 100644--- a/.skills/discourse-upcoming-changes-authoring/SKILL.md+++ b/.skills/discourse-upcoming-changes-authoring/SKILL.md@@ -24,7 +24,7 @@ Key methods to understand:- `settings_hidden_while_enabled` — Returns the set of *other* site setting names that should be hidden from admins because an enabled change declares them in its `hide_settings:` metadata. Computed live (not toggled at opt-in time) so it tracks both opt-in paths and is multisite-safe. See [Hiding Settings While Enabled](#hiding-settings-while-enabled) below.-**`UpcomingChanges::ConditionalDisplay`** (defined inside `lib/upcoming_changes.rb`) — Hides individual upcoming changes from the admin UI when they don't make sense in the current context (e.g. a Horizon-related change on a site without Horizon installed). Define a `should_display_<upcoming_change_name>?` class method on it to gate a specific change; if no method is defined, the change is always displayed. See [Conditional Display](#conditional-display) below.+**`UpcomingChanges::ConditionalDisplay`** (defined inside `lib/upcoming_changes.rb`) — Hides individual upcoming changes from the admin UI when they don't make sense in the current context (e.g. a Horizon-related change on a site without Horizon installed). Core gates can define a `should_display_<upcoming_change_name>?` class method on it; plugin-owned upcoming changes should use `Plugin::Instance#register_upcoming_change_conditional_display`. If no rule is defined, the change is always displayed. See [Conditional Display](#conditional-display) below.**`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.@@ -142,8 +142,8 @@ Some upcoming changes only make sense to show admins under certain conditions#### How It Works1. **Filtering** — `UpcomingChanges::List#fetch_upcoming_changes` calls `UpcomingChanges::ConditionalDisplay.should_display?(setting_name)` on every change after the status filter, before group/image enrichment. Changes that return `false` are dropped from the result entirely.-2. **Resolution** — `should_display?` checks for a class method named `should_display_<upcoming_change_name>?` on `ConditionalDisplay`. If defined, its return value is used; otherwise the change is always displayed (returns `true`).-3. **Definition site** — Add the gating method directly to the `ConditionalDisplay` class, typically next to (or inside) the relevant subsystem's code — e.g. a Horizon-specific gate can live with the Horizon code as long as `UpcomingChanges::ConditionalDisplay` is reopened to define it. Group related gates together for discoverability.+2. **Resolution** — `should_display?` first checks for a class method named `should_display_<upcoming_change_name>?` on `ConditionalDisplay`. If defined, its return value is used. Otherwise it evaluates enabled plugin callbacks registered for that setting. If no method or callback is defined, the change is always displayed (returns `true`).+3. **Definition site** — Core gates can live directly on `ConditionalDisplay`, typically next to the relevant subsystem's code. Plugin gates should be registered from the plugin initializer via `register_upcoming_change_conditional_display(:setting_name) { ... }` so disabled plugins are filtered by `DiscoursePluginRegistry`.#### Key Behaviors@@ -298,7 +298,13 @@ Valid value sets:To hide an upcoming change from the admin UI under certain conditions:-1. Reopen `UpcomingChanges::ConditionalDisplay` and define a class method named `should_display_<upcoming_change_name>?` that returns a boolean:+1. For plugin-owned changes, register a callback from `plugin.rb`:+ ```ruby+ register_upcoming_change_conditional_display(:enable_plugin_feature) do+ SiteSetting.some_dependency_enabled+ end+ ```+2. For core changes, reopen `UpcomingChanges::ConditionalDisplay` and define a class method named `should_display_<upcoming_change_name>?` that returns a boolean:```rubymodule UpcomingChangesclass ConditionalDisplay@@ -308,10 +314,10 @@ To hide an upcoming change from the admin UI under certain conditions:endend```-2. Place the reopen near the related subsystem (e.g. inside the Horizon plugin) so the gate lives with the code that owns the condition.-3. If the check is expensive, memoize inside the method — `List` calls `should_display?` once per change.-4. No registration step is needed; `should_display?` finds the method dynamically via `respond_to?`.-5. Test by stubbing the predicate — see [Testing Conditional Display](#testing-conditional-display).+3. Place core gates near the related subsystem so the gate lives with the code that owns the condition.+4. If the check is expensive, memoize inside the method or callback — `List` calls `should_display?` once per change.+5. Multiple plugin callbacks for the same setting are combined with `all?`, so any enabled plugin can hide the change.+6. Test by stubbing the predicate or registering a callback — see [Testing Conditional Display](#testing-conditional-display).### Adding a Default Override@@ -412,7 +418,15 @@ expect(SiteSetting.suggested_topics_max_days_old).to eq(730)### Testing Conditional Display-Stub the predicate method directly on `UpcomingChanges::ConditionalDisplay` rather than redefining it — this avoids leaking method definitions across examples:+For plugin-owned changes, test the registry path:++```ruby+Plugin::Instance+ .new+ .register_upcoming_change_conditional_display(:enable_plugin_feature) { false }+```++For core changes, stub the predicate method directly on `UpcomingChanges::ConditionalDisplay` rather than redefining it — this avoids leaking method definitions across examples:```rubyUpcomingChanges::ConditionalDisplaydiff --git a/lib/discourse_plugin_registry.rb b/lib/discourse_plugin_registry.rbindex 74148dcf2a1..278cc6d4568 100644--- a/lib/discourse_plugin_registry.rb+++ b/lib/discourse_plugin_registry.rb@@ -138,6 +138,8 @@ class DiscoursePluginRegistrydefine_filtered_register :flag_applies_to_types+ define_filtered_register :upcoming_change_conditional_display_callbacks+define_filtered_register :calendar_subscription_feedsdefine_filtered_register :custom_filter_mappingsdiff --git a/lib/plugin/instance.rb b/lib/plugin/instance.rbindex f8687f50c68..222b48a923a 100644--- a/lib/plugin/instance.rb+++ b/lib/plugin/instance.rb@@ -427,6 +427,15 @@ class Plugin::InstanceDiscoursePluginRegistry.register_problem_check(klass, self)end+ def register_upcoming_change_conditional_display(setting_name, &block)+ raise ArgumentError, "block is required" if block.blank?++ DiscoursePluginRegistry.register_upcoming_change_conditional_display_callback(+ { setting_name: setting_name.to_sym, callback: block },+ self,+ )+ end+def custom_avatar_column(column)reloadable_patch do |plugin|UserLookup.lookup_columns << columndiff --git a/lib/upcoming_changes.rb b/lib/upcoming_changes.rbindex 183f77d4dc3..68c73148434 100644--- a/lib/upcoming_changes.rb+++ b/lib/upcoming_changes.rb@@ -7,22 +7,31 @@ module UpcomingChanges# might modify how site behavior works if another setting is enabled,# and so on.#- # You can define any should_display_<upcoming_change_name>? method to control- # whether an upcoming change should be displayed to admins, and if the- # method is undefined the change will always be displayed.+ # Core can define any should_display_<upcoming_change_name>? method to control+ # whether an upcoming change should be displayed to admins. Plugins can use+ # Plugin::Instance#register_upcoming_change_conditional_display for their own+ # upcoming changes. If no conditional display rule is defined, the change will+ # always be displayed.## Keep in mind this is called from UpcomingChanges::List service,# which loops over every change in an N1 depending on the filters admins# have selected, so caching may be appropriate at times.class ConditionalDisplaydef self.should_display?(upcoming_change_name)+ upcoming_change_name = upcoming_change_name.to_sym+return false if !UpcomingChanges.owning_plugin_configurable?(upcoming_change_name)if respond_to?("should_display_#{upcoming_change_name}?")return public_send("should_display_#{upcoming_change_name}?")end- true+ callbacks =+ DiscoursePluginRegistry.upcoming_change_conditional_display_callbacks.select do |callback|+ callback[:setting_name] == upcoming_change_name+ end++ callbacks.empty? || callbacks.all? { |callback| callback[:callback].call }enddef self.should_display_enable_horizon_high_context_topic_cards?diff --git a/spec/lib/plugin/instance_spec.rb b/spec/lib/plugin/instance_spec.rbindex 838dd333726..a87584c0023 100644--- a/spec/lib/plugin/instance_spec.rb+++ b/spec/lib/plugin/instance_spec.rb@@ -996,6 +996,37 @@ TEXTendend+ describe "#register_upcoming_change_conditional_display" do+ let(:plugin) { Plugin::Instance.new }++ before { allow(DiscoursePluginRegistry).to receive(:clear_modifiers!) }++ after do+ DiscoursePluginRegistry.reset_register!(:upcoming_change_conditional_display_callbacks)+ end++ it "requires a block" do+ expect {+ plugin.register_upcoming_change_conditional_display(:enable_upload_debug_mode)+ }.to raise_error(ArgumentError, "block is required")+ end++ it "registers a conditional display callback" do+ plugin.register_upcoming_change_conditional_display(:enable_upload_debug_mode) { false }++ callback = DiscoursePluginRegistry.upcoming_change_conditional_display_callbacks.first+ expect(callback[:setting_name]).to eq(:enable_upload_debug_mode)+ expect(callback[:callback]).to be_a(Proc)+ end++ it "normalizes setting names to symbols" do+ plugin.register_upcoming_change_conditional_display("enable_upload_debug_mode") { true }++ callback = DiscoursePluginRegistry.upcoming_change_conditional_display_callbacks.first+ expect(callback[:setting_name]).to eq(:enable_upload_debug_mode)+ end+ end+describe "#register_email_unsubscriber" dolet(:plugin) { Plugin::Instance.new }diff --git a/spec/lib/upcoming_changes_spec.rb b/spec/lib/upcoming_changes_spec.rbindex af94bb5cc71..0bd0817a6b7 100644--- a/spec/lib/upcoming_changes_spec.rb+++ b/spec/lib/upcoming_changes_spec.rb@@ -949,12 +949,59 @@ RSpec.describe UpcomingChanges doenddescribe "conditional display" do+ after do+ DiscoursePluginRegistry.reset_register!(:upcoming_change_conditional_display_callbacks)+ end+it "returns true when the conditional display method is undefined for an upcoming change" doexpect(UpcomingChanges::ConditionalDisplay.should_display?(:enable_upload_debug_mode)).to eq(true,)end+ it "returns true when the registered callback returns true" do+ Plugin::Instance+ .new+ .register_upcoming_change_conditional_display(:enable_upload_debug_mode) { true }++ expect(UpcomingChanges::ConditionalDisplay.should_display?(:enable_upload_debug_mode)).to eq(+ true,+ )+ end++ it "returns false when the registered callback returns false" do+ Plugin::Instance+ .new+ .register_upcoming_change_conditional_display(:enable_upload_debug_mode) { false }++ expect(UpcomingChanges::ConditionalDisplay.should_display?(:enable_upload_debug_mode)).to eq(+ false,+ )+ end++ it "returns false when any registered callback returns false" do+ Plugin::Instance+ .new+ .register_upcoming_change_conditional_display(:enable_upload_debug_mode) { true }+ Plugin::Instance+ .new+ .register_upcoming_change_conditional_display(:enable_upload_debug_mode) { false }++ expect(UpcomingChanges::ConditionalDisplay.should_display?(:enable_upload_debug_mode)).to eq(+ false,+ )+ end++ it "ignores callbacks from disabled plugins" do+ plugin = Plugin::Instance.new+ plugin.stubs(:enabled?).returns(false)+ plugin.register_upcoming_change_conditional_display(:enable_upload_debug_mode) { false }++ expect(UpcomingChanges::ConditionalDisplay.should_display?(:enable_upload_debug_mode)).to eq(+ true,+ )+ end+context "when the owning plugin is not configurable" dolet(:plugin_setting_name) { :enable_experimental_sample_plugin_feature }@@ -1005,6 +1052,16 @@ RSpec.describe UpcomingChanges doUpcomingChanges::ConditionalDisplay.should_display?(:enable_upload_debug_mode),).to eq(true)end++ it "takes precedence over registered callbacks" do+ Plugin::Instance+ .new+ .register_upcoming_change_conditional_display(:enable_upload_debug_mode) { false }++ expect(+ UpcomingChanges::ConditionalDisplay.should_display?(:enable_upload_debug_mode),+ ).to eq(true)+ endendcontext "when the conditional display method returns false" do