From 61a8cd6c8f9ce864ec9ada95239bfd85f1873f31 Mon Sep 17 00:00:00 2001
From: Santiago Bartesaghi <santib@hey.com>
Date: Thu, 24 Jun 2021 20:47:21 -0300
Subject: [PATCH] Deprecate replace_on_assign_to_many

---
 activestorage/CHANGELOG.md                        |  5 +++++
 .../lib/active_storage/attached/model.rb          |  6 ++++++
 activestorage/test/models/attached/many_test.rb   | 15 +++++++++++++++
 guides/source/upgrading_ruby_on_rails.md          |  2 +-
 4 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/activestorage/CHANGELOG.md b/activestorage/CHANGELOG.md
index 19c7c7bd39..c1e9144032 100644
--- a/activestorage/CHANGELOG.md
+++ b/activestorage/CHANGELOG.md
@@ -1,3 +1,8 @@
+*   Deprecate `config.active_storage.replace_on_assign_to_many`. Future versions of Rails
+    will behave the same way as when the config is set to `true`.
+
+    *Santiago Bartesaghi*
+
 *   Remove deprecated methods: `build_after_upload`, `create_after_upload!` in favor of `create_and_upload!`,
     and `service_url` in favor of `url`.
 
diff --git a/activestorage/lib/active_storage/attached/model.rb b/activestorage/lib/active_storage/attached/model.rb
index 89e41f1f35..45428a1616 100644
--- a/activestorage/lib/active_storage/attached/model.rb
+++ b/activestorage/lib/active_storage/attached/model.rb
@@ -145,6 +145,12 @@ module ActiveStorage
                   ActiveStorage::Attached::Changes::CreateMany.new("#{name}", self, attachables)
                 end
             else
+              ActiveSupport::Deprecation.warn \
+                "config.active_storage.replace_on_assign_to_many is deprecated and will be removed in Rails 7.1. " \
+                "Make sure that your code works well with config.active_storage.replace_on_assign_to_many set to true before upgrading. " \
+                "To append new attachables to the Active Storage association, prefer using `attach`. " \
+                "Using association setter would result in purging the existing attached attachments and replacing them with new ones."
+
               if Array(attachables).any?
                 attachment_changes["#{name}"] =
                   ActiveStorage::Attached::Changes::CreateMany.new("#{name}", self, #{name}.blobs + attachables)
diff --git a/activestorage/test/models/attached/many_test.rb b/activestorage/test/models/attached/many_test.rb
index ac633520d0..29a1eb4fb2 100644
--- a/activestorage/test/models/attached/many_test.rb
+++ b/activestorage/test/models/attached/many_test.rb
@@ -777,6 +777,21 @@ class ActiveStorage::ManyAttachedTest < ActiveSupport::TestCase
     end
   end
 
+  test "deprecation warning when replace_on_assign_to_many is false" do
+    append_on_assign do
+      message = <<-MSG.squish
+        DEPRECATION WARNING: config.active_storage.replace_on_assign_to_many is deprecated and will be removed in Rails 7.1.
+        Make sure that your code works well with config.active_storage.replace_on_assign_to_many set to true before upgrading.
+        To append new attachables to the Active Storage association, prefer using `attach`.
+        Using association setter would result in purging the existing attached attachments and replacing them with new ones.
+      MSG
+
+      assert_deprecated(message) do
+        @user.update! highlights: [create_blob(filename: "whenever.jpg")]
+      end
+    end
+  end
+
   private
     def append_on_assign
       ActiveStorage.replace_on_assign_to_many, previous = false, ActiveStorage.replace_on_assign_to_many
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index eb16f3332e..98b2d19180 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -697,7 +697,7 @@ user.highlights.first.filename # => "funky.jpg"
 user.highlights.second.filename # => "town.jpg"
 ```
 
-Existing applications can opt in to this new behavior by setting `config.active_storage.replace_on_assign_to_many` to `true`. The old behavior will be deprecated in Rails 6.1 and removed in a subsequent release.
+Existing applications can opt in to this new behavior by setting `config.active_storage.replace_on_assign_to_many` to `true`. The old behavior will be deprecated in Rails 7.0 and removed in Rails 7.1.
 
 Upgrading from Rails 5.1 to Rails 5.2
 -------------------------------------