shrine 3.0.0 → 3.2.2

data/doc/refile.md

@@ -1,12 +1,12 @@
 ---
-title: Shrine for Refile Users
+title: Upgrading from Refile
 ---
 
 This guide is aimed at helping Refile users transition to Shrine, and it consists
 of three parts:
 
 1. Explanation of the key differences in design between Refile and Shrine
-2. Instructions how to migrate and existing app that uses Refile to Shrine
+2. Instructions how to migrate an existing app that uses Refile to Shrine
 3. Extensive reference of Refile's interface with Shrine equivalents
 
 ## Overview
@@ -110,13 +110,6 @@ into separate columns.
 Shrine provides on-the-fly processing via the
 [`derivation_endpoint`][derivation_endpoint] plugin:
 
-```rb
-# config/routes.rb (Rails)
-Rails.application.routes.draw do
-  # ...
-  mount ImageUploader.derivation_endpoint => "/derivations/image"
-end
-```
 ```rb
 require "image_processing/mini_magick"
 
@@ -132,8 +125,15 @@ class ImageUploader < Shrine
   end
 end
 ```
+```rb
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  # ...
+  mount ImageUploader.derivation_endpoint => "/derivations/image"
+end
+```
 
-Shrine also support processing up front using the [`derivatives`][derivatives]
+Shrine also support eager processing using the [`derivatives`][derivatives]
 plugin.
 
 ### Validation
@@ -199,13 +199,18 @@ explains this setup in more detail.
 ## Migrating from Refile
 
 You have an existing app using Refile and you want to transfer it to
-Shrine. Let's assume we have a `Photo` model with the "image" attachment. First
-we need to create the `image_data` column for Shrine:
+Shrine. Let's assume we have a `Photo` model with the "image" attachment.
+
+### 1. Add Shrine column
+
+First we need to create the `image_data` column for Shrine:
 
 ```rb
 add_column :photos, :image_data, :text
 ```
 
+### 2. Dual write
+
 Afterwards we need to make new uploads write to the `image_data` column. This
 can be done by including the below module to all models that have Refile
 attachments:
@@ -219,8 +224,7 @@ Shrine.storages = {
 }
 
 Shrine.plugin :model
-```
-```rb
+
 module RefileShrineSynchronization
   def write_shrine_data(name)
     attacher = Shrine::Attacher.from_model(self, name)
@@ -257,8 +261,12 @@ end
 ```
 
 After you deploy this code, the `image_data` column should now be successfully
-synchronized with new attachments.  Next step is to run a script which writes
-all existing Refile attachments to `image_data`:
+synchronized with new attachments.
+
+### 3. Data migration
+
+Next step is to run a script which writes all existing Refile attachments to
+`image_data`:
 
 ```rb
 Photo.find_each do |photo|
@@ -267,9 +275,22 @@ Photo.find_each do |photo|
 end
 ```
 
+### 4. Rewrite code
+
 Now you should be able to rewrite your application so that it uses Shrine
-instead of Refile, using equivalent Shrine storages. For help with translating
-the code from Refile to Shrine, you can consult the reference below.
+instead of Refile (you can consult the reference in the next section). You can
+remove the `RefileShrineSynchronization` module as well.
+
+### 5. Remove Refile columns
+
+If everything is looking good, we can remove Refile columns:
+
+```rb
+remove_column :photos, :image_id
+remove_column :photos, :image_size
+remove_column :photos, :image_filename
+remove_column :photos, :image_content_type
+```
 
 ## Refile to Shrine direct mapping
 

data/doc/release_notes/2.19.0.md

@@ -16,7 +16,7 @@ title: Shrine 2.19.0
   uploaded_file.download
   uploaded_file.delete
   ```
-  ```plaintext
+  ```
   Metadata (32ms) – {:storage=>:store, :io=>StringIO, :uploader=>Shrine}
   Upload (1523ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :io=>StringIO, :upload_options=>{}, :uploader=>Shrine}
   Exists (755ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}

data/doc/release_notes/3.0.0.md

@@ -3,312 +3,326 @@ title: Shrine 3.0.0
 ---
 
 This guide covers all the changes in the 3.0.0 version of Shrine. If you're
-currently using Shrine 2.x, see [Upgrading to Shrine 3.x] for instructions on
-how to upgrade.
+currently using Shrine 2.x, see **[Upgrading to Shrine 3.x]** for instructions
+on how to upgrade.
 
 ## Major features
 
-* The new **[`derivatives`][derivatives]** plugin has been added for storing
-  additional processed files alongside the main file.
+### Derivatives
 
-  ```rb
-  Shrine.plugin :derivatives
-  ```
-  ```rb
-  class ImageUploader < Shrine
-    Attacher.derivatives_processor do |original|
-      magick = ImageProcessing::MiniMagick.source(original) 
-
-      {
-        large:  magick.resize_to_limit!(800, 800),
-        medium: magick.resize_to_limit!(500, 500),
-        small:  magick.resize_to_limit!(300, 300),
-      }
-    end
-  end
-  ```
-  ```rb
-  photo = Photo.new(photo_params)
-  photo.image_derivatives! # creates derivatives
-  photo.save
-  ```
-
-  This is a rewrite of the [`versions`][versions] plugin, bringing numerous
-  improvements:
-
-  - processed files are separated from the main file
-
-    ```rb
-    photo.image_data #=>
-    # {
-    #   "id": "original.jpg",
-    #   "storage": "store",
-    #   "metadata": { ... },
-    #   "derivatives": {
-    #     "large": { "id": "large.jpg", "storage": "store", "metadata": { ... } },
-    #     "medium": { "id": "medium.jpg", "storage": "store", "metadata": { ... } },
-    #     "small": { "id": "small.jpg", "storage": "store", "metadata": { ... } }
-    #   }
-    # }
-
-    photo.image             #=> #<Shrine::UploadedFile @id="original.jpg" ...>
-    photo.image_derivatives #=>
-    # {
-    #   large: #<Shrine::UploadedFile @id="large.jpg" ...>,
-    #   medium: #<Shrine::UploadedFile @id="medium.jpg" ...>,
-    #   small: #<Shrine::UploadedFile @id="small.jpg" ...>,
-    # }
-    ```
-
-  - processing is decoupled from promotion
-
-    ```rb
-    photo = Photo.create(image: file) # promote original file to permanent storage
-    photo.image_derivatives!          # generate derivatives after promotion
-    photo.save                        # save derivatives data
-    ```
-
-  - ability to add or remove processed files at any point
-
-    ```rb
-    class ImageUploader < Shrine
-      Attacher.derivatives_processor :thumbnails do |original|
-        # ...
-      end
-
-      Attacher.derivatives_processor :crop do |original, left:, top:, width:, height:|
-        vips = ImageProcessing::Vips.source(original)
-
-        { cropped: vips.crop!(left, top, width, height) }
-      end
-    end
-    ```
-    ```rb
-    photo.image_derivatives!(:thumbnails)
-    photo.image_derivatives #=> { large: ..., medium: ..., small: ... }
-    photo.save
-
-    # ... sometime later ...
-
-    photo.image_derivatives!(:crop, left: 0, top: 0, width: 300, height: 300)
-    photo.image_derivatives #=> { large: ..., medium: ..., small: ..., cropped: ... }
-    photo.save
-    ```
+The new **[`derivatives`][derivatives]** plugin has been added for storing
+additional processed files alongside the main file.
 
-  - possibility of uploading processed files to different storage
+```rb
+Shrine.plugin :derivatives
+```
+```rb
+class ImageUploader < Shrine
+  Attacher.derivatives_processor do |original|
+    magick = ImageProcessing::MiniMagick.source(original) 
 
-    ```rb
-    class ImageUploader < Shrine
-      # specify storage for all derivatives
-      Attacher.derivatives_storage :other_store
-
-      # or specify storage per derivative
-      Attacher.derivatives_storage { |derivative| :other_store }
-    end
-    ```
-    ```rb
-    photo = Photo.create(image: file)
-    photo.image.storage_key #=> :store
+    {
+      large:  magick.resize_to_limit!(800, 800),
+      medium: magick.resize_to_limit!(500, 500),
+      small:  magick.resize_to_limit!(300, 300),
+    }
+  end
+end
+```
+```rb
+photo = Photo.new(photo_params)
+photo.image_derivatives! # creates derivatives
+photo.save
+```
 
-    photo.image_derivatives!
-    photo.image_derivatives[:large].storage_key #=> :other_store
-    ```
+This is a rewrite of the [`versions`][versions] plugin, bringing numerous
+improvements:
 
-* The [`Shrine::Attacher`][attacher] class has been rewritten and can now be
-  used without models:
+* processed files are separated from the main file
 
   ```rb
-  attacher = Shrine::Attacher.new
-  attacher.attach(file)
-  attacher.file #=> #<Shrine::UploadedFile>
+  photo.image_data #=>
+  # {
+  #   "id": "original.jpg",
+  #   "storage": "store",
+  #   "metadata": { ... },
+  #   "derivatives": {
+  #     "large": { "id": "large.jpg", "storage": "store", "metadata": { ... } },
+  #     "medium": { "id": "medium.jpg", "storage": "store", "metadata": { ... } },
+  #     "small": { "id": "small.jpg", "storage": "store", "metadata": { ... } }
+  #   }
+  # }
+
+  photo.image             #=> #<Shrine::UploadedFile id="original.jpg" ...>
+  photo.image_derivatives #=>
+  # {
+  #   large: #<Shrine::UploadedFile id="large.jpg" ...>,
+  #   medium: #<Shrine::UploadedFile id="medium.jpg" ...>,
+  #   small: #<Shrine::UploadedFile id="small.jpg" ...>,
+  # }
   ```
 
-  The `Attacher#data`, `Attacher#load_data`, and `Attacher.from_data` methods
-  have been added for dumping and loading the attached file:
+* processing is decoupled from promotion
 
   ```rb
-  # dump attached file into a serializable Hash
-  data = attacher.data #=> { "id" => "abc123.jpg", "storage" => "store", "metadata" => { ... } }
-  ```
-  ```rb
-  # initialize attacher from attached file data...
-  attacher = Shrine::Attacher.from_data(data)
-  attacher.file #=> #<Shrine::UploadedFile @id="abc123.jpg" @storage_key=:store @metadata={...}>
-
-  # ...or load attached file into an existing attacher
-  attacher = Shrine::Attacher.new
-  attacher.load_data(data)
-  attacher.file #=> #<Shrine::UploadedFile>
+  photo = Photo.create(image: file) # promote original file to permanent storage
+  photo.image_derivatives!          # generate derivatives after promotion
+  photo.save                        # save derivatives data
   ```
 
-  Several more methods have been added:
+- ability to add or remove processed files at any point
 
-  - `Attacher#attach` – attaches the file directly to permanent storage
-  - `Attacher#attach_cached` – extracted from `Attacher#assign`
-  - `Attacher#upload` – calls `Shrine#upload`, passing `:record` and `:name` context
-  - `Attacher#file` – alias for `Attacher#get`
-  - `Attacher#cache_key` – returns temporary storage key (`:cache` by default)
-  - `Attacher#store_key` – returns permanent storage key (`:store` by default)
-
-* The new [`column`][column] plugin adds the ability to serialize attached file
-  data, in format suitable for writing into a database column.
-
-  ```rb
-  Shrine.plugin :column
-  ```
   ```rb
-  # dump attached file data into a JSON string
-  data = attacher.column_data #=> '{"id":"abc123.jpg","storage":"store","metadata":{...}}'
-  ```
-  ```rb
-  # initialize attacher from attached file data...
-  attacher = Shrine::Attacher.from_column(data)
-  attacher.file #=> #<Shrine::UploadedFile @id="abc123.jpg" @storage_key=:store @metadata={...}>
-
-  # ...or load attached file into an existing attacher
-  attacher = Shrine::Attacher.new
-  attacher.load_column(data)
-  attacher.file #=> #<Shrine::UploadedFile>
-  ```
+  class ImageUploader < Shrine
+    Attacher.derivatives_processor :thumbnails do |original|
+      # ...
+    end
 
-* The new [`entity`][entity] plugin adds support for immutable structs, which
-  are commonly used with ROM, Hanami and dry-rb.
+    Attacher.derivatives_processor :crop do |original, left:, top:, width:, height:|
+      vips = ImageProcessing::Vips.source(original)
 
-  ```rb
-  Shrine.plugin :entity
-  ```
-  ```rb
-  class Photo < Hanami::Entity
-    include Shrine::Attachment(:image)
+      { cropped: vips.crop!(left, top, width, height) }
+    end
   end
   ```
   ```rb
-  photo = Photo.new(image_data: '{"id":"abc123.jpg","storage":"store","metadata":{...}}')
-  photo.image #=> #<Shrine::UploadedFile @id="abc123.jpg" @storage_key=:store ...>
-  ```
+  photo.image_derivatives!(:thumbnails)
+  photo.image_derivatives #=> { large: ..., medium: ..., small: ... }
+  photo.save
 
-* The new [`model`][model] plugin adds support for mutable structs, which is
-  used by `activerecord` and `sequel` plugins.
+  # ... sometime later ...
 
-  ```rb
-  Shrine.plugin :model
-  ```
-  ```rb
-  class Photo < Struct.new(:image_data)
-    include Shrine::Attachment(:image)
-  end
-  ```
-  ```rb
-  photo = Photo.new
-  photo.image = file
-  photo.image #=> #<Shrine::UploadedFile @id="abc123.jpg" @storage_key=:cache ...>
-  photo.image_data #=> #=> '{"id":"abc123.jpg", "storage":"cache", "metadata":{...}}'
+  photo.image_derivatives!(:crop, left: 0, top: 0, width: 300, height: 300)
+  photo.image_derivatives #=> { large: ..., medium: ..., small: ..., cropped: ... }
+  photo.save
   ```
 
-* The [`backgrounding`][backgrounding] plugin has been rewritten for more
-  flexibility and simplicity. The new usage is much more explicit:
+* possibility of uploading processed files to different storage
 
   ```rb
-  Shrine.plugin :backgrounding
-  Shrine::Attacher.promote_block do
-    PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
-  end
-  Shrine::Attacher.destroy_block do
-    DestroyJob.perform_async(self.class.name, data)
-  end
-  ```
-  ```rb
-  class PromoteJob
-    include Sidekiq::Worker
-
-    def perform(attacher_class, record_class, record.id, name, file_data)
-      attacher_class = Object.const_get(attacher_class)
-      record         = Object.const_get(record_class).find(record_id) # if using Active Record
+  class ImageUploader < Shrine
+    # specify storage for all derivatives
+    Attacher.derivatives_storage :other_store
 
-      attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
-      attacher.atomic_promote
-    rescue Shrine::AttachmentChanged, ActiveRecord::RecordNotFound
-      # attachment has changed or the record has been deleted, nothing to do
-    end
+    # or specify storage per derivative
+    Attacher.derivatives_storage { |derivative| :other_store }
   end
   ```
   ```rb
-  class DestroyJob
-    include Sidekiq::Worker
-
-    def perform(attacher_class, data)
-      attacher_class = Object.const_get(attacher_class)
+  photo = Photo.create(image: file)
+  photo.image.storage_key #=> :store
+
+  photo.image_derivatives!
+  photo.image_derivatives[:large].storage_key #=> :other_store
+  ```
+
+### Attacher redesign
+
+The [`Shrine::Attacher`][attacher] class has been rewritten and can now be
+used without models:
+
+```rb
+attacher = Shrine::Attacher.new
+attacher.attach(file)
+attacher.file #=> #<Shrine::UploadedFile>
+```
+
+The `Attacher#data`, `Attacher#load_data`, and `Attacher.from_data` methods
+have been added for dumping and loading the attached file:
+
+```rb
+# dump attached file into a serializable Hash
+data = attacher.data #=> { "id" => "abc123.jpg", "storage" => "store", "metadata" => { ... } }
+```
+```rb
+# initialize attacher from attached file data...
+attacher = Shrine::Attacher.from_data(data)
+attacher.file #=> #<Shrine::UploadedFile id="abc123.jpg" storage=:store metadata={...}>
+
+# ...or load attached file into an existing attacher
+attacher = Shrine::Attacher.new
+attacher.load_data(data)
+attacher.file #=> #<Shrine::UploadedFile>
+```
+
+Several more methods have been added:
+
+- `Attacher#attach` – attaches the file directly to permanent storage
+- `Attacher#attach_cached` – extracted from `Attacher#assign`
+- `Attacher#upload` – calls `Shrine#upload`, passing `:record` and `:name` context
+- `Attacher#file` – alias for `Attacher#get`
+- `Attacher#cache_key` – returns temporary storage key (`:cache` by default)
+- `Attacher#store_key` – returns permanent storage key (`:store` by default)
+
+#### Column
+
+The new [`column`][column] plugin adds the ability to serialize attached file
+data, in format suitable for writing into a database column.
+
+```rb
+Shrine.plugin :column
+```
+```rb
+# dump attached file data into a JSON string
+data = attacher.column_data #=> '{"id":"abc123.jpg","storage":"store","metadata":{...}}'
+```
+```rb
+# initialize attacher from attached file data...
+attacher = Shrine::Attacher.from_column(data)
+attacher.file #=> #<Shrine::UploadedFile id="abc123.jpg" storage=:store metadata={...}>
+
+# ...or load attached file into an existing attacher
+attacher = Shrine::Attacher.new
+attacher.load_column(data)
+attacher.file #=> #<Shrine::UploadedFile>
+```
+
+#### Entity
+
+The new [`entity`][entity] plugin adds support for immutable structs, which
+are commonly used with ROM, Hanami and dry-rb.
+
+```rb
+Shrine.plugin :entity
+```
+```rb
+class Photo < Hanami::Entity
+  include Shrine::Attachment(:image)
+end
+```
+```rb
+photo = Photo.new(image_data: '{"id":"abc123.jpg","storage":"store","metadata":{...}}')
+photo.image #=> #<Shrine::UploadedFile id="abc123.jpg" storage=:store ...>
+```
+
+#### Model
+
+The new [`model`][model] plugin adds support for mutable structs, which is
+used by `activerecord` and `sequel` plugins.
+
+```rb
+Shrine.plugin :model
+```
+```rb
+class Photo < Struct.new(:image_data)
+  include Shrine::Attachment(:image)
+end
+```
+```rb
+photo = Photo.new
+photo.image = file
+photo.image #=> #<Shrine::UploadedFile id="abc123.jpg" storage=:cache ...>
+photo.image_data #=> #=> '{"id":"abc123.jpg", "storage":"cache", "metadata":{...}}'
+```
+
+### Backgrounding rewrite
 
-      attacher = attacher_class.from_data(data)
-      attacher.destroy
-    end
+* The [`backgrounding`][backgrounding] plugin has been rewritten for more
+flexibility and simplicity. The new usage is much more explicit:
+
+```rb
+Shrine.plugin :backgrounding
+Shrine::Attacher.promote_block do
+  PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
+end
+Shrine::Attacher.destroy_block do
+  DestroyJob.perform_async(self.class.name, data)
+end
+```
+```rb
+class PromoteJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record.id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
+    attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
+    attacher.atomic_promote
+  rescue Shrine::AttachmentChanged, ActiveRecord::RecordNotFound
+    # attachment has changed or the record has been deleted, nothing to do
   end
-  ```
+end
+```
+```rb
+class DestroyJob
+  include Sidekiq::Worker
 
-  There are several main differences compared to the old implementation:
-
-  - we are in charge of passing the record to the background job
-  - we can access the attacher before promotion
-  - we can react to errors that caused promotion to abort
-
-  We can now also register backgrounding hooks on an attacher instance, allowing
-  us to pass additional parameters to the background job:
-
-  ```rb
-  photo = Photo.new(photo_params)
+  def perform(attacher_class, data)
+    attacher_class = Object.const_get(attacher_class)
 
-  photo.image_attacher.promote_block do |attacher|
-    PromoteJob.perform_async(
-      attacher.class.name,
-      attacher.record.class.name,
-      attacher.record.id,
-      attacher.name,
-      attacher.file_data,
-      current_user.id, # <== parameters from the controller
-    )
+    attacher = attacher_class.from_data(data)
+    attacher.destroy
   end
+end
+```
 
-  photo.save # will call our instance-level backgrounding hook
-  ```
+There are several main differences compared to the old implementation:
 
-* The persistence plugins (`activerecord`, `sequel`) now implement a unified
-  [persistence] interface:
+- we are in charge of passing the record to the background job
+- we can access the attacher before promotion
+- we can react to errors that caused promotion to abort
 
-  | Method                    | Description                                           |
-  | :-----------------        | :----------                                           |
-  | `Attacher#persist`        | persists attachment data                              |
-  | `Attacher#atomic_persist` | persists attachment data if attachment hasn’t changed |
-  | `Attacher#atomic_promote` | promotes cached file and atomically persists changes  |
+We can now also register backgrounding hooks on an attacher instance, allowing
+us to pass additional parameters to the background job:
 
-  The "atomic" methods use the new [`atomic_helpers`][atomic_helpers] plugin,
-  and are useful for background jobs. For example, this is how we'd use them to
-  implement metadata extraction in the background in a concurrency-safe way:
+```rb
+photo = Photo.new(photo_params)
 
-  ```rb
-  MetadataJob.perform_async(
+photo.image_attacher.promote_block do |attacher|
+  PromoteJob.perform_async(
     attacher.class.name,
     attacher.record.class.name,
     attacher.record.id,
     attacher.name,
     attacher.file_data,
+    current_user.id, # <== parameters from the controller
   )
-  ```
-  ```rb
-  class MetadataJob
-    include Sidekiq::Worker
-
-    def perform(attacher_class, record_class, record_id, name, file_data)
-      attacher_class = Object.const_get(attacher_class)
-      record         = Object.const_get(record_class).find(record_id) # if using Active Record
-
-      attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
-      attacher.refresh_metadata! # extract metadata
-      attacher.atomic_persist    # persist if attachment hasn't changed
-    rescue Shrine::AttachmentChanged, ActiveRecord::RecordNotFound
-      # attachment has changed or record has been deleted, nothing to do
-    end
+end
+
+photo.save # will call our instance-level backgrounding hook
+```
+
+### Persistence interface
+
+The persistence plugins (`activerecord`, `sequel`) now implement a unified
+[persistence] interface:
+
+| Method                    | Description                                           |
+| :-----------------        | :----------                                           |
+| `Attacher#persist`        | persists attachment data                              |
+| `Attacher#atomic_persist` | persists attachment data if attachment hasn’t changed |
+| `Attacher#atomic_promote` | promotes cached file and atomically persists changes  |
+
+The "atomic" methods use the new [`atomic_helpers`][atomic_helpers] plugin,
+and are useful for background jobs. For example, this is how we'd use them to
+implement metadata extraction in the background in a concurrency-safe way:
+
+```rb
+MetadataJob.perform_async(
+  attacher.class.name,
+  attacher.record.class.name,
+  attacher.record.id,
+  attacher.name,
+  attacher.file_data,
+)
+```
+```rb
+class MetadataJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record_id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
+    attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
+    attacher.refresh_metadata! # extract metadata
+    attacher.atomic_persist    # persist if attachment hasn't changed
+  rescue Shrine::AttachmentChanged, ActiveRecord::RecordNotFound
+    # attachment has changed or record has been deleted, nothing to do
   end
-  ```
+end
+```
 
 ## Other new plugins
 
@@ -352,8 +366,8 @@ how to upgrade.
   ```
   ```rb
   attacher = photo.image_attacher
-  attacher.form_assign("image" => file, "title" => "...", "description" => "...")
-  attacher.file #=> #<Shrine::UploadedFile @id="..." @storage_key=:cache ...>
+  attacher.form_assign({ "image" => file, "title" => "...", "description" => "..." })
+  attacher.file #=> #<Shrine::UploadedFile id="..." storage=:cache ...>
   ```
 
 ## Other features
@@ -686,6 +700,9 @@ how to upgrade.
 * The `Attacher#replace` method has been renamed to
   `Attacher#destroy_previous`.
 
+* The `Attacher#assign` method now raises an exception when non-cached uploaded
+  file is assigned.
+
 * The `Attacher#attached?` method now returns whether a file is attached,
   regardless of whether it was changed or not.