deprecate_soft 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f38db5179c81ba2e97d0a09bebeea87648eed96271b87a0089c3e444d122c9f5
-  data.tar.gz: fba061e831a26a0cf0be6bd99970cf84dd4130d3d93b6e53fbe01f5fa0b2846d
+  metadata.gz: 71f04af257e3e75e4c00ab45333c7e800a440f29f7677361bb6057d300eb6553
+  data.tar.gz: 62e5028bb462ac1cfec9d91a462baaaca81ba0f9211392c387cbff926aaf5a06
 SHA512:
-  metadata.gz: 5d5d5ed40760cb78b41399924db249e93c585eef04f2f5d370c2cbfcfcfd5ae1621cea064c1b681e3ab90a16f63b814afe48c50ed5c4f4d32144602e7288ee49
-  data.tar.gz: 0124ae4b6a825c3a5920b2bee96417e73a44b9c19f527797cc35e7c852e43b5867369b04c0167a2efa2728eed8b7e99c894e9d74464ca09b36a8aef3c98bce64
+  metadata.gz: 93a50dfb57c19b479a103192f8e86f2bd3abed9bf1400db03e6ad4d1f3aba1eddd67eff0226a101b8c3d3813d69839e7ac505a8feb38252a521d1c9038b9a3aa
+  data.tar.gz: 7ffb74d9dfdf8d2051d20a7fa1c8efca196248bd2c8358e8077534f7900bea851ef30868c6a5cb3ed267b3b49ed2ebecb9fea166394b0280c5ebe284036b00de

data/.rubocop.yml

@@ -1,11 +1,14 @@
 AllCops:
   TargetRubyVersion: 2.5 # purposely an old Ruby version
 
-Style/StringLiterals:
-  EnforcedStyle: single_quotes
+Layout/LineLength:
+  Max: 180
 
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: single_quotes
+Lint/ConstantDefinitionInBlock:
+  Enabled: false
+
+Lint/UnusedBlockArgument:
+  Enabled: false
 
 Metrics/AbcSize:
   Enabled: false
@@ -22,9 +25,6 @@ Metrics/CyclomaticComplexity:
 Metrics/MethodLength:
   Enabled: false
 
-Lint/UnusedBlockArgument:
-  Enabled: false
-
 Naming/MethodParameterName:
   Enabled: false
 
@@ -34,5 +34,20 @@ Style/SafeNavigation:
 Style/Documentation:
   Enabled: false
 
+Style/IfUnlessModifier:
+  Enabled: false
+
 Style/RedundantSelf:
   Enabled: false
+
+Style/SingleLineMethods:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: single_quotes
+
+Style/TrivialAccessors:
+  Enabled: false

data/CHANGELOG.md

@@ -1,7 +1,38 @@
-## DepracateSoft Change Log
+
+## 📝 DepracateSoft Change Log
+
+## [1.2.0] - 2025-04-05
+### ✨ Added Support
+ - improving handling of class methods
+ - added deprecate_class_soft for class methods. Fixed [Issue #1](https://github.com/tilo/deprecate_soft/issues/1)
+ - support to define the method after the declaration
+### 🛠️ Internals
+ - stream-lined include DeprecateSoft
+### 📐 Deliberate Limitations
+ - Class methods need to be defined via `def self.method`, not in `class << self` blocks.
+   Simply move the to-be-deprecated method out of the `self << class` and declare it via `self.method_name`.
+   This also makes the to be deleted method stand out more.
+
+## [1.1.0] - 2025-03-29
+### ✨ Added Support
+ - Errors in `before_hook` / `after_hook` do not prevent method execution.
+ - `Kernel.warn` is used to log hook exceptions instead of raising.
+ - No impact if `deprecate_soft` is called twice for the same method
+### 🧪 Test Coverage
+ - deprecate_soft called before method definition
+ - deprecate_soft called twice
+ - deprecate_soft for private instance and class methods
+ - errors in `before_hook` or `after_hook` 
+### 🛠️ Internals
+ -  simplified initialization
 
 ## [1.0.0] - 2025-03-24
- - Initial release
+- Initial release of `deprecate_soft`.
+- Support for soft-deprecating instance and class methods, as well as private methods.
+- Added `before_hook` and `after_hook` for custom instrumentation or logging.
+- Safe wrapping of methods with optional message.
+- Skips wrapping if method is not yet defined.
+- Supports defining deprecations inline with method definitions.
+
 ## [0.0.1] - 2025-03-22
  - pre-release
- 

data/README.md

@@ -1,7 +1,11 @@
 
 # DeprecateSoft
 
-DeprecateSoft is a lightweight and flexible Ruby gem designed to help you gracefully and safely deprecate methods.
+[![Gem Version](https://badge.fury.io/rb/deprecate_soft.svg)](https://badge.fury.io/rb/deprecate_soft)
+[![CI](https://github.com/tilo/deprecate_soft/actions/workflows/main.yml/badge.svg)](https://github.com/tilo/deprecate_soft/actions/workflows/main.yml)
+[![codecov](https://codecov.io/gh/tilo/deprecate_soft/branch/main/graph/badge.svg)](https://codecov.io/gh/tilo/deprecate_soft)
+
+DeprecateSoft is a lightweight and flexible Ruby gem designed to help you gracefully and safely delete methods.
 
 It was inspired by the need to track deprecated method usage in large codebases before safely removing old code — with zero disruption and flexible metrics support.
 
@@ -11,6 +15,8 @@ It’s ideal for monitoring deprecated method usage across your application usin
 
 Once tracking confirms that a deprecated method is no longer in use, you can confidently delete it from your codebase.
 
+This mechanism has been **proven in large-scale production systems** to safely clean up legacy code — this gem reimagines that functionality to help you clean up your code with confidence.
+
 ---
 
 ## ✨ Features
@@ -19,10 +25,14 @@ Once tracking confirms that a deprecated method is no longer in use, you can con
 - Works with instance methods in any class or module
 - Works with class or module methods in any class or module
 - System-wide hook configuration (before and after)
-- No monkey-patching or global pollution
+- No monkey-patching or global pollution — unless you explicitly opt in via `GlobalMonkeyPatch`
 - Fully compatible with Rails or plain Ruby apps
 
 ---
+## 📖 Blog Posts
+- [Safely Delete Old Ruby Code with deprecate_soft](https://medium.com/@tilo-sloboda/safely-delete-old-code-with-deprecate-soft-89e819b41d52)
+---
+## 📝 [Change Log](https://github.com/tilo/deprecate_soft/blob/main/CHANGELOG.md)
 
 ## 🚀 Installation
 
@@ -38,6 +48,66 @@ Then run:
 bundle install
 ```
 
+And add your initializer file.
+
+---
+
+## 🧩 Usage
+
+Declare `deprecate_soft` **after** the method definition.
+
+### For Instance Methods:
+
+use `deprecate_soft`
+
+```ruby
+class MyService
+  include DeprecateSoft
+
+  def deprecated_method(a, b)
+    puts "doing something with #{a} and #{b}"
+  end
+
+  deprecate_soft :deprecated_method, "Use #new_method instead"
+end
+
+MyService.new.deprecated_method(1, 2) # will exercise the tracking hooks
+```
+
+### For Class Methods:
+
+use `deprecate_class_soft`
+
+```ruby
+class MyService
+  include DeprecateSoft
+
+  def self.deprecated_method(a, b)
+    puts "doing something with #{a} and #{b}"
+  end
+
+  deprecate_class_soft :deprecated_method, "will be removed" # ⚠️
+end
+
+MyService.deprecated_method(1, 2) # will exercise the tracking hooks
+
+```
+
+---
+
+## 🔐 What It Does Under the Hood
+
+When you call `deprecate_soft :method_name, "reason"`:
+
+1. It renames the original method to `__method_name_deprecated`.
+2. It defines a new method with the original name that:
+   - Calls the configured `before_hook` (if set)
+   - Delegates to the original method
+   - Calls the configured `after_hook` (if set)
+3. The optional `message` with the reason can help identifying alternatives.
+
+This ensures consistent tracking, clean method resolution, and avoids accidental bypassing.
+
 ---
 
 ## ⚙️ Configuration
@@ -96,7 +166,7 @@ end
 
 This setup ensures you can plug in **any tracking backend** you like — without polluting the global namespace.
 
-### 🔧 Customizing Method Name Wrapping
+### 🔧 Optional: Customizing Method Name Wrapping
 
 When `deprecate_soft` wraps a method, it renames the original method internally to preserve its behavior. You can customize how that internal method is named by configuring a `prefix` and `suffix`.
 
@@ -137,61 +207,6 @@ This gives you full control over how deprecated methods are renamed internally.
 
 These names are never called directly — they're used internally to wrap and preserve the original method logic.
 
-
----
-
-## 🧩 Usage
-
-🚨 Always declare `deprecate_soft` **after** the method definition!
-
-### For Instance Methods:
-
-```ruby
-class MyService
-  include DeprecateSoft
-
-  def deprecated_method(a, b)
-    puts "doing something with #{a} and #{b}"
-  end
-
-  deprecate_soft :deprecated_method, "Use #new_method instead"
-end
-
-MyService.new.deprecated_method(1, 2) # will exercise the tracking hooks
-```
-
-### For Class Methods:
-
-```ruby
-class MyService
-  extend DeprecateSoft
-
-  def self.deprecated_method(a, b)
-    puts "doing something with #{a} and #{b}"
-  end
-
-  deprecate_soft :deprecated_method, "will be removed"
-end
-
-MyService.deprecated_method(1, 2) # will exercise the tracking hooks
-
-```
-
----
-
-## 🔐 What It Does Under the Hood
-
-When you call `deprecate_soft :method_name, "reason"`:
-
-1. It renames the original method to `__method_name_deprecated`.
-2. It defines a new method with the original name that:
-   - Calls the configured `before_hook` (if set)
-   - Delegates to the original method
-   - Calls the configured `after_hook` (if set)
-3. The optional `message` with the reason can help identifying alternatives.
-
-This ensures consistent tracking, clean method resolution, and avoids accidental bypassing.
-
 ---
 
 ## 🧪 Example Hook Logic
@@ -273,6 +288,36 @@ Klass#legacy_method:caller:app/jobs/cleanup_job.rb:88 → 4
 
 💡 Now you not only know that the method is still used -- you know where from, and how often -- so you can fix your code.
 
+--- 
+
+## 💪 Optional: Global Monkey Patching
+
+For large projects, it can be beneficial to enable deprecate_soft across the entire codebase without having to explicitly `include DeprecateSoft` or e`xtend DeprecateSoft` in each class or module.
+
+To do this, you can globally monkey-patch `Module` by including `DeprecateSoft::GlobalMonkeyPatch`. This is **entirely optional and not enabled by default**.
+
+Add the following to your `config/initializers/deprecate_soft.rb` initializer:
+
+```ruby
+# config/initializers/deprecate_soft.rb
+
+require "deprecate_soft"
+require "deprecate_soft/global_monkey_patch"
+
+# ... 
+
+class Module
+  include DeprecateSoft::GlobalMonkeyPatch
+end
+
+DeprecateSoft.configure do |config|
+  #
+  # ...  
+  #
+end
+
+```
+
 ---
 
 ## 🛡 Best Practices
@@ -280,7 +325,7 @@ Klass#legacy_method:caller:app/jobs/cleanup_job.rb:88 → 4
 - Use `deprecate_soft` for methods you plan to remove but want to confirm they are no longer used.
 - Integrate with your observability platform for tracking.
 - Review usage stats before deleting deprecated methods from your code.
-- 🚨 Always declare `deprecate_soft` **after** the method definition! 🚨
+- Always declare `deprecate_soft` **after** the method definition.
 
 ---
 
@@ -289,7 +334,9 @@ Klass#legacy_method:caller:app/jobs/cleanup_job.rb:88 → 4
 - Make sure hooks do not raise or interfere with production behavior.
 - Only use non-blocking, low-latency methods for tracking!
 - Currently assumes Ruby 2.5+ (for `&.` and keyword args support).
-- Currently keeps the visibility of the renamed original method the same (does not make it private).
+- Class methods need to be defined via `def self.method`, not in `class << self` blocks.
+  Simply move the to-be-deprecated method out of the `self << class` and declare it via `self.method_name`.
+  This also makes the to be deleted method stand out more.
 
 ---
 
@@ -297,9 +344,9 @@ Klass#legacy_method:caller:app/jobs/cleanup_job.rb:88 → 4
 
 Feel free to open issues or pull requests if you'd like to:
 
-- Add support for class methods
+- Request new features
 - Add Railtie for automatic setup
-- Add built-in backends (e.g. Redis, StatsD)
+- Add support for other backends
 
 ---
 

data/lib/deprecate_soft/global_monkey_patch.rb

@@ -3,17 +3,13 @@
 module DeprecateSoft
   module GlobalMonkeyPatch
     def deprecate_soft(method_name, message)
-      if self.singleton_class.method_defined?(method_name) || self.singleton_class.private_method_defined?(method_name)
-        # Class method
-        DeprecateSoft::MethodWrapper.wrap_method(self, method_name, message, is_class_method: true)
-      elsif self.instance_methods.include?(method_name) || self.private_instance_methods.include?(method_name)
-        # Instance method
-        DeprecateSoft::MethodWrapper.wrap_method(self, method_name, message, is_class_method: false)
-      else # rubocop:disable Style/EmptyElse
-        #  protect against declaring deprecate_soft before method is defined
-        #
-        # Do nothing — fail-safe in production
-      end
+      extend DeprecateSoft::ClassMethods unless is_a?(DeprecateSoft::ClassMethods)
+      deprecate_soft(method_name, message)
+    end
+
+    def deprecate_class_soft(method_name, message = nil)
+      extend DeprecateSoft::ClassMethods unless is_a?(DeprecateSoft::ClassMethods)
+      deprecate_class_soft(method_name, message)
     end
   end
 end

data/lib/deprecate_soft/method_wrapper.rb

@@ -6,27 +6,57 @@ module DeprecateSoft
       hidden_method_name = "#{DeprecateSoft.prefix}#{method_name}_#{DeprecateSoft.suffix}"
 
       if is_class_method
+        target = context.singleton_class
+
+        return if target.method_defined?(hidden_method_name) || target.private_method_defined?(hidden_method_name)
+
         original_method = context.method(method_name)
+        target.define_method(hidden_method_name, original_method)
+
+        target.define_method(method_name) do |*args, &block|
+          klass_name = self.class.name || self.class.to_s
+          full_name = "#{klass_name}.#{method_name}"
 
-        context.singleton_class.define_method(hidden_method_name, original_method)
+          begin
+            DeprecateSoft.before_hook&.call(full_name, message, args: args)
+          rescue StandardError => e
+            warn "DeprecateSoft.before_hook error: #{e.class} - #{e.message}"
+          end
 
-        context.singleton_class.define_method(method_name) do |*args, &block|
-          full_name = "#{self.name}.#{method_name}"
-          DeprecateSoft.before_hook&.call(full_name, message, args: args) if defined?(DeprecateSoft.before_hook)
           result = send(hidden_method_name, *args, &block)
-          DeprecateSoft.after_hook&.call(full_name, message, result: result) if defined?(DeprecateSoft.after_hook)
+
+          begin
+            DeprecateSoft.after_hook&.call(full_name, message, result: result)
+          rescue StandardError => e
+            warn "DeprecateSoft.after_hook error: #{e.class} - #{e.message}"
+          end
+
           result
         end
       else
-        original_method = context.instance_method(method_name)
+        return if context.method_defined?(hidden_method_name) || context.private_method_defined?(hidden_method_name)
 
+        original_method = context.instance_method(method_name)
         context.define_method(hidden_method_name, original_method)
 
         context.define_method(method_name) do |*args, &block|
-          full_name = "#{self.class}##{method_name}"
-          DeprecateSoft.before_hook&.call(full_name, message, args: args) if defined?(DeprecateSoft.before_hook)
+          klass_name = self.class.name || self.to_s
+          full_name = "#{klass_name}.#{method_name}"
+
+          begin
+            DeprecateSoft.before_hook&.call(full_name, message, args: args)
+          rescue StandardError => e
+            warn "DeprecateSoft.before_hook error: #{e.class} - #{e.message}"
+          end
+
           result = send(hidden_method_name, *args, &block)
-          DeprecateSoft.after_hook&.call(full_name, message, result: result) if defined?(DeprecateSoft.after_hook)
+
+          begin
+            DeprecateSoft.after_hook&.call(full_name, message, result: result)
+          rescue StandardError => e
+            warn "DeprecateSoft.after_hook error: #{e.class} - #{e.message}"
+          end
+
           result
         end
       end

data/lib/deprecate_soft/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DeprecateSoft
-  VERSION = '1.0.0'
+  VERSION = '1.2.0'
 end

data/lib/deprecate_soft.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-require_relative 'deprecate_soft/version'
-
-require_relative 'deprecate_soft/method_wrapper'
+# require all files under lib/deprecate_soft
+Dir[File.join(__dir__, 'deprecate_soft', '*.rb')].sort.each do |file|
+  require file
+end
 
 module DeprecateSoft
   class << self
@@ -21,30 +22,57 @@ module DeprecateSoft
       yield self
     end
 
-    def included(base)
-      base.extend InstanceMethods
+    def prefixed_name(method_name)
+      "#{prefix}#{method_name}_#{suffix}".to_sym
     end
 
-    def extended(base)
-      base.extend ClassMethods
-    end
-  end
+    def included(base)
+      base.extend(ClassMethods)
 
-  module InstanceMethods
-    def deprecate_soft(method_name, message)
-      #  protect against declaring deprecate_soft before method is defined
-      return unless method_defined?(method_name) || private_method_defined?(method_name)
+      base.define_singleton_method(:method_added) do |method_name|
+        pending = base.instance_variable_get(:@__pending_soft_wraps)
+        if pending&.key?(method_name)
+          DeprecateSoft::MethodWrapper.wrap_method(base, method_name, pending.delete(method_name), is_class_method: false)
+        end
+        super(method_name) if defined?(super)
+      end
 
-      DeprecateSoft::MethodWrapper.wrap_method(self, method_name, message, is_class_method: false)
+      base.singleton_class.define_method(:singleton_method_added) do |method_name|
+        pending = instance_variable_get(:@_pending_soft_wraps)
+        if pending&.key?(method_name)
+          DeprecateSoft::MethodWrapper.wrap_method(base, method_name, pending.delete(method_name), is_class_method: true)
+        end
+        super(method_name) if defined?(super)
+      end
     end
   end
 
   module ClassMethods
-    def deprecate_soft(method_name, message)
-      #  protect against declaring deprecate_soft before method is defined
-      return unless singleton_class.method_defined?(method_name) || singleton_class.private_method_defined?(method_name)
+    def deprecate_soft(method_name, message = nil)
+      hidden = DeprecateSoft.prefixed_name(method_name)
+
+      if method_defined?(method_name) || private_method_defined?(method_name)
+        return if method_defined?(hidden) || private_method_defined?(hidden)
+
+        DeprecateSoft::MethodWrapper.wrap_method(self, method_name, message, is_class_method: false)
+      else
+        @__pending_soft_wraps ||= {}
+        @__pending_soft_wraps[method_name] = message
+      end
+    end
+
+    def deprecate_class_soft(method_name, message = nil)
+      hidden = DeprecateSoft.prefixed_name(method_name)
+      target = singleton_class
+
+      if target.method_defined?(method_name) || target.private_method_defined?(method_name)
+        return if target.method_defined?(hidden) || target.private_method_defined?(hidden)
 
-      DeprecateSoft::MethodWrapper.wrap_method(self, method_name, message, is_class_method: true)
+        DeprecateSoft::MethodWrapper.wrap_method(self, method_name, message, is_class_method: true)
+      else
+        @_pending_soft_wraps ||= {}
+        @_pending_soft_wraps[method_name] = message
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: deprecate_soft
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Tilo Sloboda
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-25 00:00:00.000000000 Z
+date: 2025-04-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dogstatsd-ruby
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -80,6 +94,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |
   DeprecateSoft is a lightweight Ruby gem that lets you gracefully deprecate methods
   in your codebase without breaking functionality. It wraps existing instance or