cmdx 1.1.2 → 1.5.0

data/docs/deprecation.md

@@ -4,242 +4,159 @@ Task deprecation provides a systematic approach to managing legacy tasks in CMDx
 
 ## Table of Contents
 
-- [TLDR](#tldr)
-- [Deprecation Fundamentals](#deprecation-fundamentals)
-- [Deprecation Modes](#deprecation-modes)
-- [Configuration Examples](#configuration-examples)
-- [Migration Strategies](#migration-strategies)
-- [Error Handling](#error-handling)
-- [Best Practices](#best-practices)
+- [Modes](#modes)
+  - [Raise](#raise)
+  - [Log](#log)
+  - [Warn](#warn)
+- [Declarations](#declarations)
+  - [Symbol or String](#symbol-or-string)
+  - [Boolean or Nil](#boolean-or-nil)
+  - [Method](#method)
+  - [Proc or Lambda](#proc-or-lambda)
+  - [Class or Module](#class-or-module)
 
-## TLDR
+## Modes
 
-```ruby
-# Prevent task execution completely
-class LegacyTask < CMDx::Task
-  cmd_setting!(deprecated: :error)
-end
-
-# Log deprecation warnings
-class OldTask < CMDx::Task
-  cmd_setting!(deprecated: :log)
-end
-
-# Issue Ruby warnings
-class ObsoleteTask < CMDx::Task
-  cmd_setting!(deprecated: :warning)
-end
-
-# Usage triggers appropriate deprecation handling
-LegacyTask.call   # → raises DeprecationError
-OldTask.call      # → logs warning via task.logger
-ObsoleteTask.call # → issues Ruby warning
-```
+### Raise
 
-## Deprecation Fundamentals
-
-> [!NOTE]
-> Task deprecation is configured using the `cmd_setting!` declaration and processed automatically by CMDx before task execution. The deprecation system integrates seamlessly with existing logging and error handling infrastructure.
-
-### How It Works
-
-1. **Configuration**: Tasks declare deprecation mode using `cmd_setting!(deprecated: mode)`
-2. **Processing**: CMDx automatically calls `TaskDeprecator.call(task)` during task lifecycle
-3. **Action**: Appropriate deprecation handling occurs based on configured mode
-4. **Execution**: Task proceeds normally (unless `:error` mode prevents it)
-
-### Available Modes
-
-| Mode | Behavior | Use Case |
-|------|----------|----------|
-| `:error` | Raises `DeprecationError` | Hard deprecation, prevent execution |
-| `:log` | Logs warning via `task.logger.warn` | Soft deprecation, track usage |
-| `:warning` | Issues Ruby warning | Development alerts |
-| `true` | Same as `:log` | Legacy boolean support |
-| `nil/false` | No deprecation handling | Default behavior |
-
-## Deprecation Modes
-
-### Error Mode (Hard Deprecation)
+`:raise` mode prevents task execution entirely. Use this for tasks that should no longer be used under any circumstances.
 
 > [!WARNING]
-> Error mode prevents task execution entirely. Use this for tasks that should no longer be used under any circumstances.
+> Use `:raise` mode carefully in production environments as it will break existing workflows immediately.
 
 ```ruby
-class ProcessLegacyPaymentTask < CMDx::Task
-  cmd_setting!(deprecated: :error)
+class ProcessObsoleteAPI < CMDx::Task
+  settings(deprecated: :raise)
 
-  def call
-    # This code will never execute
-    charge_customer(amount)
+  def work
+    # Will never execute...
   end
 end
 
-# Attempting to use deprecated task
-result = ProcessLegacyPaymentTask.call(amount: 100)
-# → raises CMDx::DeprecationError: "ProcessLegacyPaymentTask usage prohibited"
+result = ProcessObsoleteAPI.execute
+#=> raises CMDx::DeprecationError: "ProcessObsoleteAPI usage prohibited"
 ```
 
-### Log Mode (Soft Deprecation)
+### Log
 
-> [!TIP]
-> Log mode allows continued usage while tracking deprecation warnings. Perfect for gradual migration scenarios where immediate replacement isn't feasible.
+`:log` mode allows continued usage while tracking deprecation warnings. Perfect for gradual migration scenarios where immediate replacement isn't feasible.
 
 ```ruby
-class ProcessOldPaymentTask < CMDx::Task
-  cmd_setting!(deprecated: :log)
+class ProcessLegacyFormat < CMDx::Task
+  settings(deprecated: :log)
+
+  # Same
+  settings(deprecated: true)
 
-  def call
-    # Task executes normally but logs deprecation warning
-    charge_customer(amount)
+  def work
+    # Executes but logs deprecation warning...
   end
 end
 
-# Task executes with logged warning
-result = ProcessOldPaymentTask.call(amount: 100)
-result.successful? # → true
+result = ProcessLegacyFormat.execute
+result.successful? #=> true
 
-# Check logs for deprecation warning:
-# WARN -- : DEPRECATED: migrate to replacement or discontinue use
+# Deprecation warning appears in logs:
+# WARN -- : DEPRECATED: ProcessLegacyFormat - migrate to replacement or discontinue use
 ```
 
-### Warning Mode (Development Alerts)
+### Warn
 
-> [!NOTE]
-> Warning mode issues Ruby warnings visible in development and testing environments. Useful for alerting developers without affecting production logging.
+`:warn` mode issues Ruby warnings visible in development and testing environments. Useful for alerting developers without affecting production logging.
 
 ```ruby
-class ProcessObsoletePaymentTask < CMDx::Task
-  cmd_setting!(deprecated: :warning)
+class ProcessOldData < CMDx::Task
+  settings(deprecated: :warn)
 
-  def call
-    # Task executes with Ruby warning
-    charge_customer(amount)
+  def work
+    # Executes but emits Ruby warning...
   end
 end
 
-# Task executes with Ruby warning
-result = ProcessObsoletePaymentTask.call(amount: 100)
-# stderr: [ProcessObsoletePaymentTask] DEPRECATED: migrate to replacement or discontinue use
+result = ProcessOldData.execute
+result.successful? #=> true
 
-result.successful? # → true
+# Ruby warning appears in stderr:
+# [ProcessOldData] DEPRECATED: migrate to replacement or discontinue use
 ```
 
-## Configuration Examples
+## Declarations
 
-### Environment-Specific Deprecation
+### Symbol or String
 
 ```ruby
-class ExperimentalFeatureTask < CMDx::Task
-  # Different deprecation behavior per environment
-  cmd_setting!(
-    deprecated: Rails.env.production? ? :error : :warning
-  )
-
-  def call
-    enable_experimental_feature
-  end
+class OutdatedConnector < CMDx::Task
+  # Symbol
+  settings(deprecated: :raise)
+
+  # String
+  settings(deprecated: "warn")
 end
 ```
 
-### Conditional Deprecation
+### Boolean or Nil
 
 ```ruby
-class LegacyIntegrationTask < CMDx::Task
-  # Deprecate only for specific conditions
-  cmd_setting!(
-    deprecated: -> { ENV['NEW_API_ENABLED'] == 'true' ? :log : nil }
-  )
-
-  def call
-    call_legacy_api
-  end
+class OutdatedConnector < CMDx::Task
+  # Deprecates with default :log mode
+  settings(deprecated: true)
+
+  # Skips deprecation
+  settings(deprecated: false)
+  settings(deprecated: nil)
 end
 ```
 
-## Migration Strategies
+### Method
 
-> [!IMPORTANT]
-> When deprecating tasks, always provide clear migration paths and replacement implementations to minimize disruption.
+```ruby
+class OutdatedConnector < CMDx::Task
+  # Symbol
+  settings(deprecated: :deprecated?)
+
+  def work
+    # Your logic here...
+  end
 
-### Graceful Fallback
+  private
 
-```ruby
-class NotificationTask < CMDx::Task
-  cmd_setting!(deprecated: :log)
-
-  def call
-    # Provide fallback while encouraging migration
-    logger.warn "Consider migrating to NotificationServiceV2"
-
-    # Delegate to new service but maintain compatibility
-    NotificationServiceV2.send_notification(
-      recipient: recipient,
-      message: message,
-      delivery_method: :legacy
-    )
+  def deprecated?
+    Time.now.year > 2024 ? :raise : false
   end
 end
 ```
 
-## Error Handling
-
-### Catching Deprecation Errors
+### Proc or Lambda
 
 ```ruby
-begin
-  result = LegacyTask.call(params)
-rescue CMDx::DeprecationError => e
-  # Handle deprecation gracefully
-  Rails.logger.error "Attempted to use deprecated task: #{e.message}"
-
-  # Use replacement task instead
-  result = ReplacementTask.call(params)
-end
+class OutdatedConnector < CMDx::Task
+  # Proc
+  settings(deprecated: proc { Rails.env.development? ? :raise : :log })
 
-if result.successful?
-  # Process successful result
-else
-  # Handle task failure
+  # Lambda
+  settings(deprecated: -> { Current.tenant.legacy_mode? ? :warn : :raise })
 end
 ```
 
-## Best Practices
-
-### Documentation and Communication
-
-> [!TIP]
-> Always document deprecation reasons, timelines, and migration paths. Clear communication prevents confusion and reduces support burden.
+### Class or Module
 
 ```ruby
-class LegacyReportTask < CMDx::Task
-  # Document deprecation clearly
-  cmd_setting!(deprecated: :log)
-
-  # Class-level documentation
-  # @deprecated Use ReportGeneratorV2Task instead
-  # @see ReportGeneratorV2Task
-  # @note This task will be removed in v2.0.0
-  # @since 1.5.0 marked as deprecated
-
-  def call
-    # Add inline documentation
-    logger.warn <<~DEPRECATION
-      LegacyReportTask is deprecated and will be removed in v2.0.0.
-      Please migrate to ReportGeneratorV2Task which provides:
-      - Better performance
-      - Enhanced error handling
-      - More flexible output formats
-
-      Migration guide: https://docs.example.com/migration/reports
-    DEPRECATION
-
-    generate_legacy_report
+class OutdatedTaskDeprecator
+  def call(task)
+    task.class.name.include?("Outdated")
   end
 end
+
+class OutdatedConnector < CMDx::Task
+  # Class or Module
+  settings(deprecated: OutdatedTaskDeprecator)
+
+  # Instance
+  settings(deprecated: OutdatedTaskDeprecator.new)
+end
 ```
 
 ---
 
-- **Prev:** [Testing](testing.md)
-- **Next:** [AI Prompts](ai_prompts.md)
+- **Prev:** [Internationalization (i18n)](internationalization.md)
+- **Next:** [Workflows](workflows.md)