Skip to content

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.md
index 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 Works
1. **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:
```ruby
module UpcomingChanges
class ConditionalDisplay
@@ -308,10 +314,10 @@ To hide an upcoming change from the admin UI under certain conditions:
end
end
```
-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:
```ruby
UpcomingChanges::ConditionalDisplay
diff --git a/lib/discourse_plugin_registry.rb b/lib/discourse_plugin_registry.rb
index 74148dcf2a1..278cc6d4568 100644
--- a/lib/discourse_plugin_registry.rb
+++ b/lib/discourse_plugin_registry.rb
@@ -138,6 +138,8 @@ class DiscoursePluginRegistry
define_filtered_register :flag_applies_to_types
+ define_filtered_register :upcoming_change_conditional_display_callbacks
+
define_filtered_register :calendar_subscription_feeds
define_filtered_register :custom_filter_mappings
diff --git a/lib/plugin/instance.rb b/lib/plugin/instance.rb
index f8687f50c68..222b48a923a 100644
--- a/lib/plugin/instance.rb
+++ b/lib/plugin/instance.rb
@@ -427,6 +427,15 @@ class Plugin::Instance
DiscoursePluginRegistry.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 << column
diff --git a/lib/upcoming_changes.rb b/lib/upcoming_changes.rb
index 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 ConditionalDisplay
def 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 }
end
def self.should_display_enable_horizon_high_context_topic_cards?
diff --git a/spec/lib/plugin/instance_spec.rb b/spec/lib/plugin/instance_spec.rb
index 838dd333726..a87584c0023 100644
--- a/spec/lib/plugin/instance_spec.rb
+++ b/spec/lib/plugin/instance_spec.rb
@@ -996,6 +996,37 @@ TEXT
end
end
+ 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" do
let(:plugin) { Plugin::Instance.new }
diff --git a/spec/lib/upcoming_changes_spec.rb b/spec/lib/upcoming_changes_spec.rb
index af94bb5cc71..0bd0817a6b7 100644
--- a/spec/lib/upcoming_changes_spec.rb
+++ b/spec/lib/upcoming_changes_spec.rb
@@ -949,12 +949,59 @@ RSpec.describe UpcomingChanges do
end
describe "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" do
expect(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" do
let(:plugin_setting_name) { :enable_experimental_sample_plugin_feature }
@@ -1005,6 +1052,16 @@ RSpec.describe UpcomingChanges do
UpcomingChanges::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)
+ end
end
context "when the conditional display method returns false" do