active_record_compose 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 690ecf032eb0a4c59c97394702c838142a4d519145f72e58f9a381d956cad5ce
-  data.tar.gz: 7133a2f5defa0d1c97dac41b207936512f6d5375e8f534ea77dc6c13c3f61dde
+  metadata.gz: 9b1f795843fd29ef6dcd9cf17e897938ea97fc8f32db35f0b444b36455e619a3
+  data.tar.gz: 584e44a2c49c6861ad232f0c52c75b6d73abb550f39165fabe14690a71575c81
 SHA512:
-  metadata.gz: 2680382210cf6eb2f8371cca7e656f8b00211361f00bf9aed7d2ee4f006a816eee6298a917e48c67d5b4f6149545f2ebb3e67bd5905946279c9e203e9e378d82
-  data.tar.gz: 63aa5b0a8abcbcd59eb81aadadf4c8207622988ad417b09d2e8f977615ed8726233ae8f257f8d8847e16e38f400955e0bda1d9340f9c7733f06ea8d76fa4854a
+  metadata.gz: 04bc96e1479134c02ad09ae5d014ad5ad93c6d6ae6914a39724d42152f691120ccfaa76c681e3790bb1b436b49cc39d57eb8bfe7f6fc73d064818e22738ce1c9
+  data.tar.gz: e757a94164248e188c46413a706ec2418eb99c97f28bc5631305620c064b8fd7b04a6621d4809e405f95ac4d2228c22509700169f0049b581a1998ceba364acd

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [0.8.1] - 2025-06-21
+
+- Add migration guide message.
+- Add upper version.
+
 ## [0.8.0] - 2025-02-22
 
 - changed `persisted_flag_callback_control` default from `false` to `true`.

data/UPGRADE.md

@@ -0,0 +1,113 @@
+# Migration Guide: `active_record_compose` 0.8.x to 0.9.0+
+
+⚠️ **Breaking Change**
+
+This guide explains how to migrate from version **0.8.x** to **0.9.0 or later**, assuming that your codebase includes:
+
+```ruby
+self.persisted_flag_callback_control = false
+```
+
+This setting was officially **deprecated** in 0.9.0 and is **no longer supported**. Migration is required to adopt the current default behavior.
+
+## Background
+
+In version **0.7.x**, the default value of `persisted_flag_callback_control` was `false`.
+
+In **0.8.x**, the default was changed to `true`.
+If you are still using `false` in your models, it means you have **explicitly overridden the default**, likely to preserve backward-compatible behavior.
+
+This guide helps you safely migrate to the new behavior while preserving intended callback semantics.
+
+## Goal of the Migration
+
+- Remove any use of `persisted_flag_callback_control = false`
+- Adjust callback definitions to align with the semantics of `#persisted?`
+
+## Step 1 – Remove Deprecated Flag
+
+Find and remove all instances of:
+
+```diff
+-self.persisted_flag_callback_control = false
+```
+
+## Step 2 – Understand Callback Behavior Changes
+
+With `persisted_flag_callback_control = true`, whether a callback is fired depends on the return value of `#persisted?`, not the method used (`create` or `update`).
+
+### When saving with `#update`:
+
+If `persisted?` returns `false`, then:
+
+- `before_update`
+- `after_update`
+- `around_update`
+
+will **not** be triggered.
+
+✅ Recommended fix:
+
+If you don’t differentiate between creation and update phases, switch to `*_save` callbacks:
+
+```diff
+- before_update :track_change
++ before_save :track_change
+```
+
+### When saving with `#create`:
+
+If `persisted?` returns `true`, then:
+
+- `before_create`
+- `after_create`
+- `around_create`
+
+will **not** be triggered.
+
+✅ Recommended fix:
+
+Again, prefer `*_save` if you're using shared logic across creation and update:
+
+```diff
+- after_create :send_notification
++ after_save :send_notification
+```
+
+## Step 3 – Override `#persisted?` if Needed
+
+If your composed model wraps an ActiveRecord instance and delegates its persistence logic, be sure to override `#persisted?` to reflect the correct state:
+
+```ruby
+class Foo < ActiveRecordCompose::Model
+  def initialize(bar = Bar.new)
+    super()
+    @bar = bar
+  end
+
+  def persisted? = bar.persisted?
+
+  private
+
+  attr_reader :bar
+end
+```
+
+## Migration Checklist ✅
+
+- [ ] All models now `persisted_flag_callback_control` omit it entirely
+- [ ] All callback definitions have been reviewed and updated
+- [ ] Any `*_create` or `*_update` callbacks have been replaced with `*_save` where applicable
+- [ ] `#persisted?` is correctly overridden where needed
+- [ ] All tests pass and expected callbacks are fired
+
+## Why This Change?
+
+By aligning callback behavior with `persisted?`, you gain:
+
+- Clearer intent and semantics
+- More accurate behavior when composing or wrapping persisted models
+- Improved compatibility with Rails conventions
+- Less surprising callback triggering
+
+If you have questions or run into edge cases, feel free to [open an issue](https://github.com/hamajyotan/active_record_compose/issues) or start a discussion.

data/lib/active_record_compose/model.rb

@@ -82,7 +82,8 @@ module ActiveRecordCompose
           deprecator.warn(
             'The behavior with `persisted_flag_callback_control` set to `false` will be removed in 0.9.0. ' \
             'Use `self.persisted_flag_callback_control = true` set to `true`. ' \
-            '(Alternatively, exclude statements that set `false`)',
+            '(Alternatively, exclude statements that set `false`) ' \
+            'cf. https://github.com/hamajyotan/active_record_compose/blob/v0.8.1/UPGRADE.md ',
           )
           # steep:ignore:end
           run_callbacks(:save) { save_models(bang: false) }
@@ -108,7 +109,8 @@ module ActiveRecordCompose
           deprecator.warn(
             'The behavior with `persisted_flag_callback_control` set to `false` will be removed in 0.9.0. ' \
             'Use `self.persisted_flag_callback_control = true` set to `true`. ' \
-            '(Alternatively, exclude statements that set `false`)',
+            '(Alternatively, exclude statements that set `false`) ' \
+            'cf. https://github.com/hamajyotan/active_record_compose/blob/v0.8.1/UPGRADE.md ',
           )
           # steep:ignore:end
           run_callbacks(:save) { save_models(bang: true) }
@@ -151,7 +153,8 @@ module ActiveRecordCompose
       deprecator.warn(
         'The behavior with `persisted_flag_callback_control` set to `false` will be removed in 0.9.0. ' \
         'Use `self.persisted_flag_callback_control = true` set to `true`. ' \
-        '(Alternatively, exclude statements that set `false`)',
+        '(Alternatively, exclude statements that set `false`) ' \
+        'cf. https://github.com/hamajyotan/active_record_compose/blob/v0.8.1/UPGRADE.md ',
       )
       # steep:ignore:end
 
@@ -177,7 +180,8 @@ module ActiveRecordCompose
       deprecator.warn(
         'The behavior with `persisted_flag_callback_control` set to `false` will be removed in 0.9.0. ' \
         'Use `self.persisted_flag_callback_control = true` set to `true`. ' \
-        '(Alternatively, exclude statements that set `false`)',
+        '(Alternatively, exclude statements that set `false`) ' \
+        'cf. https://github.com/hamajyotan/active_record_compose/blob/v0.8.1/UPGRADE.md ',
       )
       # steep:ignore:end
 
@@ -226,7 +230,8 @@ module ActiveRecordCompose
           deprecator.warn(
             'The behavior with `persisted_flag_callback_control` set to `false` will be removed in 0.9.0. ' \
             'Use `self.persisted_flag_callback_control = true` set to `true`. ' \
-            '(Alternatively, exclude statements that set `false`)',
+            '(Alternatively, exclude statements that set `false`) ' \
+            'cf. https://github.com/hamajyotan/active_record_compose/blob/v0.8.1/UPGRADE.md ',
           )
           # steep:ignore:end
           with_callbacks(context: :update) { save_models(bang: false) }
@@ -250,7 +255,8 @@ module ActiveRecordCompose
           deprecator.warn(
             'The behavior with `persisted_flag_callback_control` set to `false` will be removed in 0.9.0. ' \
             'Use `self.persisted_flag_callback_control = true` set to `true`. ' \
-            '(Alternatively, exclude statements that set `false`)',
+            '(Alternatively, exclude statements that set `false`) ' \
+            'cf. https://github.com/hamajyotan/active_record_compose/blob/v0.8.1/UPGRADE.md ',
           )
           # steep:ignore:end
           with_callbacks(context: :update) { save_models(bang: true) }
@@ -293,12 +299,14 @@ module ActiveRecordCompose
 
     def raise_on_save_error_message = 'Failed to save the model.'
 
+    # steep:ignore:start
     def deprecator
       if ActiveRecord.respond_to?(:deprecator)
-        ActiveRecord.deprecator # steep:ignore
+        ActiveRecord.deprecator
       else # for rails 7.0.x or lower
         ActiveSupport::Deprecation
       end
     end
+    # steep:ignore:end
   end
 end

data/lib/active_record_compose/transaction_support.rb

@@ -18,7 +18,7 @@ module ActiveRecordCompose
 
       def with_connection(&) = ar_class.with_connection(&) # steep:ignore
 
-      def composite_primary_key? = false
+      def composite_primary_key? = false # steep:ignore
 
       private
 

data/lib/active_record_compose/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveRecordCompose
-  VERSION = '0.8.0'
+  VERSION = '0.8.1'
 end

data/lib/active_record_compose.rb

@@ -7,3 +7,15 @@ require_relative 'active_record_compose/model'
 
 module ActiveRecordCompose
 end
+
+if ActiveRecordCompose::VERSION == '0.8.1'
+  unless ENV['ACTIVE_RECORD_COMPOSE_SILENCE_DEPRECATION'] # rubocop:disable Style/SoleNestedConditional
+    warn <<~WARN
+
+      [DEPRECATION] You are using active_record_compose version 0.8.1, which is deprecated.
+      Please upgrade to the latest version.
+      See: https://github.com/hamajyotan/active_record_compose/blob/v0.8.1/UPGRADE.md
+
+    WARN
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_record_compose
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - hamajyotan
 bindir: bin
 cert_chain: []
-date: 2025-02-22 00:00:00.000000000 Z
+date: 2025-06-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,6 +16,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -23,6 +26,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.1'
 description: activemodel form object pattern. it embraces multiple AR models and provides
   a transparent interface as if they were a single model.
 email:
@@ -36,6 +42,7 @@ files:
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
+- UPGRADE.md
 - lib/active_record_compose.rb
 - lib/active_record_compose/composed_collection.rb
 - lib/active_record_compose/delegate_attribute.rb
@@ -52,8 +59,17 @@ metadata:
   homepage_uri: https://github.com/hamajyotan/active_record_compose
   source_code_uri: https://github.com/hamajyotan/active_record_compose
   changelog_uri: https://github.com/hamajyotan/active_record_compose/blob/main/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/active_record_compose/0.8.0
+  documentation_uri: https://www.rubydoc.info/gems/active_record_compose/0.8.1
   rubygems_mfa_required: 'true'
+post_install_message: |2+
+
+  Notice: This version (0.8.1) is deprecated.
+
+  Please upgrade to the latest version of `active_record_compose` as soon as possible.
+  Future releases will not support this version.
+
+  See https://github.com/hamajyotan/active_record_compose/blob/v0.8.1/UPGRADE.md for migration steps.
+
 rdoc_options: []
 require_paths:
 - lib
@@ -72,3 +88,4 @@ rubygems_version: 3.6.2
 specification_version: 4
 summary: activemodel form object pattern
 test_files: []
+...