3 files changed, 58 insertions, 5 deletions
diff --git a/guides/source/6_0_release_notes.md b/guides/source/6_0_release_notes.md
index c152076628..7c5478a03d 100644
--- a/guides/source/6_0_release_notes.md
+++ b/guides/source/6_0_release_notes.md
@@ -672,6 +672,12 @@ Please refer to the [Changelog][active-storage] for detailed changes.
     is saved instead of immediately.
     ([Pull Request](https://github.com/rails/rails/pull/33303))
 
+*   Optionally replace existing files instead of adding to them when assigning to
+    a collection of attachments (as in `@user.update!(images: [ … ])`). Use
+    `config.active_storage.replace_on_assign_to_many` to control this behavior.
+    ([Pull Request](https://github.com/rails/rails/pull/33303),
+     [Pull Request](https://github.com/rails/rails/pull/36716))
+
 *   Add the ability to reflect on defined attachments using the existing
     Active Record reflection mechanism.
     ([Pull Request](https://github.com/rails/rails/pull/33018))
@@ -688,10 +694,6 @@ Please refer to the [Changelog][active-storage] for detailed changes.
     `mini_magick` directly.
     ([Pull Request](https://github.com/rails/rails/pull/32471))
 
-*   Replace existing images instead of adding to them when updating an
-    attached model via `update` or `update!` with, say, `@user.update!(images: [ … ])`.
-    ([Pull Request](https://github.com/rails/rails/pull/33303))
-
 Active Model
 ------------
 
diff --git a/guides/source/configuring.md b/guides/source/configuring.md
index e53e8b4e92..4e0224b61e 100644
--- a/guides/source/configuring.md
+++ b/guides/source/configuring.md
@@ -881,7 +881,9 @@ text/javascript image/svg+xml application/postscript application/x-shockwave-fla
   config.active_storage.routes_prefix = '/files'
   ```
 
-  The default is `/rails/active_storage`
+  The default is `/rails/active_storage`.
+
+* `config.active_storage.replace_on_assign_to_many` determines whether assigning to a collection of attachments declared with `has_many_attached` replaces any existing attachments or appends to them. The default is `true`.
 
 ### Results of `load_defaults`
 
@@ -917,6 +919,7 @@ text/javascript image/svg+xml application/postscript application/x-shockwave-fla
 - `config.active_job.return_false_on_aborted_enqueue`: `true`
 - `config.active_storage.queues.analysis`: `:active_storage_analysis`
 - `config.active_storage.queues.purge`: `:active_storage_purge`
+- `config.active_storage.replace_on_assign_to_many`: `true`
 - `config.active_record.collection_cache_versioning`: `true`
 
 ### Configuring a Database
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index f17955e022..05980d1614 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -398,6 +398,54 @@ config.load_defaults "6.0"
 config.autoloader = :classic
 ```
 
+### Active Storage assignment behavior change
+
+In Rails 5.2, assigning to a collection of attachments declared with `has_many_attached` appended new files:
+
+```ruby
+class User < ApplicationRecord
+  has_many_attached :highlights
+end
+
+user.highlights.attach(filename: "funky.jpg", ...)
+user.higlights.count # => 1
+
+blob = ActiveStorage::Blob.create_after_upload!(filename: "town.jpg", ...)
+user.update!(highlights: [ blob ])
+
+user.highlights.count # => 2
+user.highlights.first.filename # => "funky.jpg"
+user.highlights.second.filename # => "town.jpg"
+```
+
+With the default configuration for Rails 6.0, assigning to a collection of attachments replaces existing files
+instead of appending to them. This matches Active Record behavior when assigning to a collection association:
+
+```ruby
+user.highlights.attach(filename: "funky.jpg", ...)
+user.highlights.count # => 1
+
+blob = ActiveStorage::Blob.create_after_upload!(filename: "town.jpg", ...)
+user.update!(highlights: [ blob ])
+
+user.highlights.count # => 1
+user.highlights.first.filename # => "town.jpg"
+```
+
+`#attach` can be used to add new attachments without removing the existing ones:
+
+```ruby
+blob = ActiveStorage::Blob.create_after_upload!(filename: "town.jpg", ...)
+user.highlights.attach(blob)
+
+user.highlights.count # => 2
+user.highlights.first.filename # => "funky.jpg"
+user.highlights.second.filename # => "town.jpg"
+```
+
+Opt in to the new default 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.
+
 Upgrading from Rails 5.1 to Rails 5.2
 -------------------------------------