feat: add deprecation warning infrastructure for renamed config keys

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Deprecation warning infrastructure — `SolidStackWeb.deprecator` exposes a gem-scoped `ActiveSupport::Deprecation` instance registered with `app.deprecators`; a private `deprecated_config` helper generates forwarding writers with warnings for any config keys renamed before 1.0
+
 ### Changed
 
 - Unify detail page layout across all three sections — cache entry detail now uses the same card-based layout as job and failed job detail pages; consolidate `sqw-detail`/`sqw-value-pre` CSS into the shared `sqw-dl`/`sqw-code-block` classes; inline margin style on the failed-job arguments card replaced with a CSS sibling-selector rule

ROADMAP.md

@@ -13,7 +13,6 @@ The path to v1.0.0 is staged: first achieve feature parity with `solid_queue_das
 ### Added
 - Complete README with configuration reference, screenshot gallery, and security guidance
 - Public API stability policy documented — breaking changes require a major version bump
-- Deprecation warnings for any config keys renamed between 0.x and 1.0
 
 ---
 

lib/solid_stack_web.rb

@@ -74,5 +74,27 @@ def authenticate(&block)
       @authenticate = block if block_given?
       @authenticate
     end
+
+    def deprecator
+      @deprecator ||= ActiveSupport::Deprecation.new("1.0", "SolidStackWeb")
+    end
+
+    private
+
+    # Define a deprecated writer for a renamed config key.
+    # The old writer issues a deprecation warning and forwards to the new key.
+    #
+    # Usage (add entries here as keys are renamed before 1.0):
+    #   deprecated_config :old_key, :new_key
+    def deprecated_config(old_key, new_key)
+      singleton_class.define_method(:"#{old_key}=") do |value|
+        deprecator.warn(
+          "config.#{old_key}= is deprecated and will be removed in SolidStackWeb 1.0. " \
+          "Use config.#{new_key}= instead.",
+          caller_locations
+        )
+        public_send(:"#{new_key}=", value)
+      end
+    end
   end
 end

lib/solid_stack_web/engine.rb

@@ -25,6 +25,10 @@ class Engine < ::Rails::Engine
       end
     end
 
+    initializer "solid_stack_web.deprecator" do |app|
+      app.deprecators[:solid_stack_web] = SolidStackWeb.deprecator
+    end
+
     initializer "solid_stack_web.pagy" do |app|
       app.config.after_initialize do
         Pagy::OPTIONS[:limit] = SolidStackWeb.page_size

spec/solid_stack_web_spec.rb

@@ -23,6 +23,33 @@
     end
   end
 
+  describe ".deprecator" do
+    it "returns an ActiveSupport::Deprecation instance scoped to SolidStackWeb" do
+      expect(SolidStackWeb.deprecator).to be_a(ActiveSupport::Deprecation)
+    end
+
+    it "returns the same instance on repeated calls" do
+      expect(SolidStackWeb.deprecator).to be(SolidStackWeb.deprecator)
+    end
+  end
+
+  describe ".deprecated_config" do
+    it "issues a deprecation warning and forwards the value to the new key" do
+      SolidStackWeb.send(:deprecated_config, :legacy_limit, :search_results_limit)
+
+      warned = false
+      SolidStackWeb.deprecator.behavior = ->(msg, *) { warned = true if msg.include?("config.legacy_limit=") }
+
+      SolidStackWeb.legacy_limit = 42
+      expect(warned).to be(true)
+      expect(SolidStackWeb.search_results_limit).to eq(42)
+    ensure
+      SolidStackWeb.search_results_limit = nil
+      SolidStackWeb.deprecator.behavior = :stderr
+      SolidStackWeb.singleton_class.remove_method(:legacy_limit=)
+    end
+  end
+
   describe ".search_results_limit" do
     it "defaults to 25" do
       expect(SolidStackWeb.search_results_limit).to eq(25)