6 files changed, 86 insertions, 97 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/active_support_core_extensions.md b/guides/source/active_support_core_extensions.md
index 8cb49ca6ae..f36cacfe8d 100644
--- a/guides/source/active_support_core_extensions.md
+++ b/guides/source/active_support_core_extensions.md
@@ -155,15 +155,6 @@ Complex(1).duplicable?      # => true
 1.method(:+).duplicable?    # => false
 ```
 
-`duplicable?` matches the current Ruby version's `dup` behavior,
-so results will vary according the version of Ruby you're using.
-In Ruby 2.4, for example, Complex and Rational are not duplicable:
-
-```ruby
-Rational(1).duplicable?     # => false
-Complex(1).duplicable?      # => false
-```
-
 WARNING: Any class can disallow duplication by removing `dup` and `clone` or raising exceptions from them. Thus only `rescue` can tell whether a given arbitrary object is duplicable. `duplicable?` depends on the hard-coded list above, but it is much faster than `rescue`. Use it only if you know the hard-coded list is enough in your use case.
 
 NOTE: Defined in `active_support/core_ext/object/duplicable.rb`.
@@ -2358,10 +2349,6 @@ There's also a related idiom that uses the splat operator:
 [*object]
 ```
 
-which in Ruby 1.8 returns `[nil]` for `nil`, and calls to `Array(object)` otherwise. (Please if you know the exact behavior in 1.9 contact fxn.)
-
-Thus, in this case the behavior is different for `nil`, and the differences with `Kernel#Array` explained above apply to the rest of `object`s.
-
 NOTE: Defined in `active_support/core_ext/array/wrap.rb`.
 
 ### Duplicating
diff --git a/guides/source/configuring.md b/guides/source/configuring.md
index e53e8b4e92..ded985debe 100644
--- a/guides/source/configuring.md
+++ b/guides/source/configuring.md
@@ -353,7 +353,7 @@ All these configuration options are delegated to the `I18n` library.
 
 * `config.active_record.lock_optimistically` controls whether Active Record will use optimistic locking and is `true` by default.
 
-* `config.active_record.cache_timestamp_format` controls the format of the timestamp value in the cache key. Default is `:nsec`.
+* `config.active_record.cache_timestamp_format` controls the format of the timestamp value in the cache key. Default is `:usec`.
 
 * `config.active_record.record_timestamps` is a boolean value which controls whether or not timestamping of `create` and `update` operations on a model occur. The default value is `true`.
 
@@ -881,7 +881,11 @@ 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`.
+
+* `config.active_storage.draw_routes` can be used to toggle Active Storage route generation. The default is `true`.
 
 ### Results of `load_defaults`
 
@@ -917,6 +921,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/engines.md b/guides/source/engines.md
index 90b08b00f0..8961a079b5 100644
--- a/guides/source/engines.md
+++ b/guides/source/engines.md
@@ -220,7 +220,7 @@ Inside the `app` directory are the standard `assets`, `controllers`, `helpers`,
 `jobs`, `mailers`, `models`, and `views` directories that you should be familiar with
 from an application. We'll look more into models in a future section, when we're writing the engine.
 
-Within the `app/assets` directory, there are the `images`, `javascripts` and
+Within the `app/assets` directory, there are the `images` and
 `stylesheets` directories which, again, you should be familiar with due to their
 similarity to an application. One difference here, however, is that each
 directory contains a sub-directory with the engine name. Because this engine is
diff --git a/guides/source/layouts_and_rendering.md b/guides/source/layouts_and_rendering.md
index 39935cd2ef..ce90a60e36 100644
--- a/guides/source/layouts_and_rendering.md
+++ b/guides/source/layouts_and_rendering.md
@@ -149,25 +149,6 @@ Rails knows that this view belongs to a different controller because of the embe
 render template: "products/show"
 ```
 
-#### Rendering an Arbitrary File
-
-The `render` method can also use a view that's entirely outside of your application:
-
-```ruby
-render file: "/u/apps/warehouse_app/current/app/views/products/show"
-```
-
-The `:file` option takes an absolute file-system path. Of course, you need to have rights
-to the view that you're using to render the content.
-
-NOTE: Using the `:file` option in combination with users input can lead to security problems
-since an attacker could use this action to access security sensitive files in your file system.
-
-NOTE: By default, the file is rendered using the current layout.
-
-TIP: If you're running Rails on Microsoft Windows, you should use the `:file` option to
-render a file, because Windows filenames do not have the same format as Unix filenames.
-
 #### Wrapping it up
 
 The above three ways of rendering (rendering another template within the controller, rendering a template within another controller, and rendering an arbitrary file on the file system) are actually variants of the same action.
@@ -178,17 +159,9 @@ In fact, in the BooksController class, inside of the update action where we want
 render :edit
 render action: :edit
 render "edit"
-render "edit.html.erb"
 render action: "edit"
-render action: "edit.html.erb"
 render "books/edit"
-render "books/edit.html.erb"
 render template: "books/edit"
-render template: "books/edit.html.erb"
-render "/path/to/rails/app/views/books/edit"
-render "/path/to/rails/app/views/books/edit.html.erb"
-render file: "/path/to/rails/app/views/books/edit"
-render file: "/path/to/rails/app/views/books/edit.html.erb"
 ```
 
 Which one you use is really a matter of style and convention, but the rule of thumb is to use the simplest one that makes sense for the code you are writing.
@@ -287,6 +260,23 @@ time.
 NOTE: Unless overridden, your response returned from this render option will be
 `text/plain`, as that is the default content type of Action Dispatch response.
 
+#### Rendering raw file
+
+Rails can render a raw file from an absolute path. This is useful for
+conditionally rendering static files like error pages.
+
+```ruby
+render file: "#{Rails.root}/public/404.html", layout: false
+```
+
+This renders the raw file (it doesn't support ERB or other handlers). By
+default it is rendered within the current layout.
+
+WARNING: Using the `:file` option in combination with users input can lead to security problems
+since an attacker could use this action to access security sensitive files in your file system.
+
+TIP: `send_file` is often a faster and better option if a layout isn't required.
+
 #### Options for `render`
 
 Calls to the `render` method generally accept five options:
@@ -303,7 +293,7 @@ Calls to the `render` method generally accept five options:
 By default, Rails will serve the results of a rendering operation with the MIME content-type of `text/html` (or `application/json` if you use the `:json` option, or `application/xml` for the `:xml` option.). There are times when you might like to change this, and you can do so by setting the `:content_type` option:
 
 ```ruby
-render file: filename, content_type: "application/rss"
+render template: "feed", content_type: "application/rss"
 ```
 
 ##### The `:layout` Option
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index 123f8dce80..05980d1614 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -184,64 +184,21 @@ That may be handy if you need to preload STIs or configure a custom inflector, f
 
 If the application being upgraded autoloads correctly, the project structure should be already mostly compatible.
 
-However, `classic` mode infers file names from missing constant names (`underscore`), whereas `zeitwerk` mode infers constant names from file names (`camelize`). These helpers are not always inverse of each other, in particular if acronyms are involved. For instance, `"FOO".underscore` is `"foo"`, but `"foo".camelize` is `"Foo"`, not `"FOO"`. Compatibility can be checked by setting `classic` mode first temporarily:
+However, `classic` mode infers file names from missing constant names (`underscore`), whereas `zeitwerk` mode infers constant names from file names (`camelize`). These helpers are not always inverse of each other, in particular if acronyms are involved. For instance, `"FOO".underscore` is `"foo"`, but `"foo".camelize` is `"Foo"`, not `"FOO"`.
 
-```ruby
-# config/application.rb
-
-config.load_defaults "6.0"
-config.autoloader = :classic
-```
-
-and then running
-
-```
-bin/rails zeitwerk:check
-```
-
-When all is good, you can delete `config.autoloader = :classic`.
-
-That checker may technically be fooled in some rare cases, but it works well in practice for projects that are running correctly in a previous versions of Rails and are being upgraded. This task tries to print a helpful report.
+Compatibility can be checked with the `zeitwerk:check` task:
 
-If that check is good, we recommend to do a second one, more strict: Eager load the application in `zeitwerk` mode. In order to do that, enable eager loading in `development` mode:
-
-```ruby
-# config/initializers/development.rb
-config.eager_load = true
-```
-
-and boot the application:
-
-```ruby
-bin/rails runner 1
 ```
-
-If a file does not match the constant it defines, you'll get a raw `NameError` explaining the discrepancy:
-
-```
-expected file ... to define constant ..., but didn't (NameError)
+$ bin/rails zeitwerk:check
+Hold on, I am eager loading the application.
+All is good!
 ```
 
-Once all is good, you'll just get a prompt back. Remember to disable `config.eager_load`, it it was false before.
-
 #### require_dependency
 
 All known use cases of `require_dependency` have been eliminated, you should grep the project and delete them.
 
-In the case of STIs with a hierarchy of more than two levels, you can preload the leaves of the hierarchy in an initializer:
-
-```ruby
-# config/initializers/preload_stis.rb
-
-# By preloading leaves, the hierarchy is loaded upwards following
-# the references to superclasses in the class definitions.
-sti_leaves = %w(
-  app/models/leaf1.rb
-  app/models/leaf2.rb
-  app/models/leaf3.rb
-)
-Rails.autoloaders.main.preload(sti_leaves)
-```
+If your application has STIs, please check their section in the guide [Autoloading and Reloading Constants (Zeitwerk Mode)](autoloading_and_reloading_constants.html#single-table-inheritance).
 
 #### Qualified names in class and module definitions
 
@@ -441,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
 -------------------------------------