shrine 3.2.2 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26dd77c39f9d5b7cc4240eacea23823453959aad469acc1d86571f129c24c347
-  data.tar.gz: 9c25f9de3f8c8be835e096da01b47c0636e03158b423a306b89895de05ca4294
+  metadata.gz: 8cfa59ed1f6143ee9298ede17eeda07dba85f0f9c3309a5b7a9e7f6c41399f29
+  data.tar.gz: 67a64a3a4f40c34797ca04279af73829acf4071eb118f78addefdbaa15e048da
 SHA512:
-  metadata.gz: 4ae941f20c889d15300bb0a3bb522f8ad9f0cbd9bb80578246bc4d5ed37b1177ecc911172a405872919210bdaa05b1e67f23d77fc97d9c827ef85b01898dd336
-  data.tar.gz: 16fbafcc5d29e70f6d0d4a36fc2123a4a8f705345021b00e87c863826d73970a7bd8116aa19ad5c3a2a03763b0e5e435398ae15a21428d0b932c52a7bb648f8e
+  metadata.gz: e87a3dbb80a304f8af559b9c3d4e8badf8e47e4377afd74fe08d570042d65358d44878c4a0366fa3cded98fe166083275e86c61f3b51d28d35e070e0233dea35
+  data.tar.gz: 83c93e76bf5513ab317ccabbdda86ce90f760e7b898dc9f40036af3e7ec915f48e55bd6f8efcf8661dacea672ce6b24b450db217815b062881169c8c90fd0cd3

data/CHANGELOG.md

@@ -1,3 +1,39 @@
+## 3.3.0 (2020-10-04)
+
+* `s3` - Support new `Aws::S3::EncryptionV2::Client` for client-side encryption (@janko)
+
+* `derivation_endpoint` – Reduce possibility of timing attacks when comparing signatures (@esparta)
+
+* `derivatives` – Avoid downloading the attached file when calling default no-op processor (@janko)
+
+* `derivatives` – Add `:download` processor setting for skipping downloading source file (@jrochkind, @janko)
+
+* `derivatives` – Copy non-file source IO objects into local file before passing them to the processor (@jrochkind)
+
+* `sequel` – Call `Attacher#reload` in `Sequel::Model#reload`, which keeps rest of attacher state (@janko, @jrochkind)
+
+* `activerecord` – Call `Attacher#reload` in `ActiveRecord::Base#reload`, which keeps rest of attacher state (@janko, @jrochkind)
+
+* `add_metadata` – Add `:skip_nil` option for excluding metadata keys whose values are nil (@renchap)
+
+* `store_dimensions` – Add `:auto_extraction` option for disabling automatically extracting dimensions on upload (@renchap)
+
+* `mirroring` – Forward original upload options when mirroring upload (@corneverbruggen)
+
+* `derivation_endpoint` – Apply `version` URL option in derivation endpoint (@janko)
+
+* `remove_attachment` – Delete removed file if a new file was attached right after removal (@janko)
+
+* `upload_endpoint` – Fix `Shrine.upload_response` not working in a Rails controller (@pldavid2)
+
+* `presign_endpoint` – Add `OPTIONS` route that newer versions of Uppy check (@janko)
+
+* `derivatives` – Add `:create_on_promote` option for auto-creating derivatives on promotion (@janko)
+
+* `s3` – Add back support for client-side encryption (@janko)
+
+* `memory` – Ensure `Memory#open` returns content in original encoding (@jrochkind)
+
 ## 3.2.2 (2020-08-05)
 
 * `s3` – Fix `S3#open` not working on aws-sdk-core 3.104 and above (@janko)

data/README.md

@@ -127,6 +127,10 @@ system.
 * Refile
 * Active Storage
 
+## Contributing
+
+Please refer to the [contributing page][Contributing].
+
 ## Code of Conduct
 
 Everyone interacting in the Shrine project’s codebases, issue trackers, and
@@ -170,3 +174,4 @@ The gem is available as open source under the terms of the [MIT License].
 [Roda]: https://github.com/jeremyevans/roda
 [CoC]: /CODE_OF_CONDUCT.md
 [MIT License]: /LICENSE.txt
+[Contributing]: https://github.com/shrinerb/shrine/blob/master/CONTRIBUTING.md

data/doc/advantages.md

@@ -93,7 +93,7 @@ low-level abstractions that give you the flexibility to build your own flow.
 ```rb
 uploaded_file = ImageUploader.upload(image, :store) # metadata extraction, upload location generation
 uploaded_file.id       #=> "44ccafc10ce6a4ff22829e8f579ee6b9.jpg"
-uplaoded_file.metadata #=> { ... extracted metadata ... }
+uploaded_file.metadata #=> { ... extracted metadata ... }
 
 data = uploaded_file.to_json # serialization
 # ...

data/doc/carrierwave.md

@@ -322,19 +322,22 @@ module CarrierwaveShrineSynchronization
 
   private
 
-  # If you'll be using `:prefix` on your Shrine storage, make sure to
-  # subtract it from the path assigned as `:id`.
   def shrine_file(uploader)
     name     = uploader.mounted_as
     filename = read_attribute(name)
-    path     = uploader.store_path(filename)
+    location = uploader.store_path(filename)
+    location = location.sub(%r{^#{storage.prefix}/}, "") if storage.prefix
 
     Shrine.uploaded_file(
       storage:  :store,
-      id:       path,
+      id:       location,
       metadata: { "filename" => filename },
     )
   end
+
+  def storage
+    Shrine.storages[:store]
+  end
 end
 ```
 ```rb

data/doc/direct_s3.md

@@ -76,6 +76,7 @@ If you're using [Uppy], this is the recommended CORS configuration for the
     <AllowedHeader>x-amz-content-sha256</AllowedHeader>
     <AllowedHeader>content-type</AllowedHeader>
     <AllowedHeader>content-disposition</AllowedHeader>
+    <ExposeHeader>ETag</ExposeHeader>
   </CORSRule>
   <CORSRule>
     <AllowedOrigin>*</AllowedOrigin>

data/doc/external/articles.md

@@ -21,7 +21,7 @@ title: Articles
 | [Asynchronous File Uploads](http://twin.github.io/file-uploads-asynchronous-world)                                           | 18 Jan 2016 |
 | [Introducing Shrine](http://twin.github.io/introducing-shrine)                                                               | 04 Oct 2015 |
 
-## Other Articles
+## Community articles
 
 | Article                                                                                                                                                                                                                                                               | Published             |
 | :------                                                                                                                                                                                                                                                               | --------:             |
@@ -32,9 +32,9 @@ title: Articles
 | [Happy users uploading files with Rails 5, Shrine, and Vue.js](https://itnext.io/happy-users-uploading-files-with-rails-5-shrine-and-vue-js-bbcc470a327f)                                                                                                             | 04 Sep 2018 |
 | [Rails 5 + Shrine + DropzoneJS](https://stephencodes.com/rails-5-shrine-dropzonejs/)                                                                                                                                                                                  | 20 Oct 2018 |
 | [How to use Trix and Shrine for WYSIWYG Editing with Drag-and-Drop Image Uploading](http://headway.io/blog/how-to-use-trix-and-shrine-for-wysiwyg-editing-with-drag-and-drop-image-uploading/)                                                                        | 26 Jan 2018 |
-| [Store Your Files on S3: Uploading from a URL](https://www.ironin.it/blog/store-your-files-on-s3-using-the-ruby-shrine-gem-part-3.html)                                                                                                                               | 28 Dec 2017 |
-| [Store Your Files on S3: Direct Uploads](https://www.ironin.it/blog/store-your-files-on-s3-using-the-ruby-shrine-gem-part-2.html)                                                                                                                                     | 15 Dec 2017 |
-| [Store Your Files on S3: Setup & Configuration](https://www.ironin.it/blog/store-your-files-on-s3-using-the-ruby-shrine-gem-part-1.html)                                                                                                                              | 27 Nov 2017 |
+| [Store Your Files on S3: Part 3 – Uploading from a URL](https://www.ironin.it/blog/store-your-files-on-s3-using-the-ruby-shrine-gem-part-3.html)                                                                                                                               | 28 Dec 2017 |
+| [Store Your Files on S3: Part 2 – Direct Uploads](https://www.ironin.it/blog/store-your-files-on-s3-using-the-ruby-shrine-gem-part-2.html)                                                                                                                                     | 15 Dec 2017 |
+| [Store Your Files on S3: Part 1 – Setup & Configuration](https://www.ironin.it/blog/store-your-files-on-s3-using-the-ruby-shrine-gem-part-1.html)                                                                                                                              | 27 Nov 2017 |
 | [Creating Streaming Radio With Rails and Icecast](https://scotch.io/tutorials/creating-online-streaming-radio-with-rails-and-icecast)                                                                                                                                 | 06 Nov 2017 |
 | [Multiple Photo Upload using Shrine](https://github.com/pyksoft/multi-photo-upload#multiple-photo-upload-using-shrine)                                                                                                                                                | 02 Nov 2017 |
 | [Uploading Files with Rails and ActionCable](https://scotch.io/tutorials/uploading-files-with-rails-and-actioncable)                                                                                                                                                  | 19 Oct 2017 |
@@ -48,14 +48,12 @@ title: Articles
 
 | Screencast                                                                                                             | Source  | Published             |
 | :----                                                                                                                  | :------ | --------:             |
+| [Testing File Uploads in Rails with Shrine](https://gorails.com/episodes/testing-file-uploads-with-shrine?autoplay=1)  | GoRails | 23 Mar 2020 |
+| [File Uploads in Rails with Shrine](https://gorails.com/episodes/rails-file-uploads-with-shrine?autoplay=1)            | GoRails | 16 Mar 2020 |
 | [Uploading Files to DigitalOcean Spaces](https://gorails.com/episodes/digital-ocean-spaces-with-rails?autoplay=1)      | GoRails | 31 Oct 2017 |
 | [Trix WYSIWYG Editor And File Uploads](https://gorails.com/episodes/trix-editor?autoplay=1)                            | GoRails | 03 Oct 2017 |
 | [Multiple File Uploads with Shrine](https://gorails.com/episodes/multiple-file-uploads-with-shrine?autoplay=1)         | GoRails | 14 Dec 2016 |
 | [Backgrounding and Video Transcoding](https://gorails.com/episodes/shrine-background-and-video-transcoding?autoplay=1) | GoRails | 03 Nov 2016 |
-| [Direct File Uploads to S3: Part 3](https://gorails.com/episodes/direct-file-uploads-to-s3-part-3?autoplay=1)          | GoRails | 05 Oct 2016 |
-| [Direct File Uploads to S3: Part 2](https://gorails.com/episodes/direct-file-uploads-to-s3-part-2?autoplay=1)          | GoRails | 05 Oct 2016 |
-| [Direct File Uploads to S3: Part 1](https://gorails.com/episodes/direct-file-uploads-to-s3-part-1?autoplay=1)          | GoRails | 05 Oct 2016 |
-| [File Uploads in Rails with Shrine](https://gorails.com/episodes/file-uploading-with-shrine?autoplay=1)                | GoRails | 23 Sep 2016 |
 
 ## Talks
 

data/doc/external/extensions.md

@@ -28,6 +28,8 @@ title: Extensions
 | :----                                                                                       | :--------                                                             |
 | [administrate-field-shrine](https://github.com/catsky/administrate-field-shrine)            | Plugin for [Administrate](https://github.com/thoughtbot/administrate) |
 | [rails_admin_shrine](https://github.com/iquest/rails_admin_shrine)                          | Plugin for [RailsAdmin](https://github.com/sferik/rails_admin)        |
+| [shrine-blurhash](https://github.com/renchap/shrine-blurhash)                               | Plugin for computing [Blurhash](https://blurha.sh/) on images         |
+| [shrine-cloudimage](https://github.com/janklimo/shrine-cloudimage)                          | Plugin for [Cloudimage](https://www.cloudimage.io/)                   |
 | [shrine-color](https://github.com/jnylen/shrine-color)                                      | Plugin for finding dominant color in an image                         |
 | [shrine-configurable_storage](https://github.com/SleeplessByte/shrine-configurable_storage) | Plugin for lazy storage registration                                  |
 | [shrine-content_addressable](https://github.com/SleeplessByte/shrine-content_addressable)   | Plugin for generating content addressable locations                   |
@@ -45,6 +47,7 @@ title: Extensions
 | Gem                                                             | Description                                                                     |
 | :-----                                                          | :-------                                                                        |
 | [ckeditor](https://github.com/galetahub/ckeditor)               | Integration for [CKEditor](https://ckeditor.com/ckeditor-4/)                    |
+| [faster_s3_url](https://github.com/jrochkind/faster_s3_url)     | Optimized generation of public and presigned AWS S3 GET URLs                    |
 | [imgproxy](https://github.com/imgproxy/imgproxy.rb)             | Integration for [imgproxy](https://github.com/imgproxy/imgproxy)                |
 | [rails_admin](https://github.com/sferik/rails_admin)            | Integration for [RailsAdmin](https://github.com/sferik/rails_admin)             |
 | [uppy-s3_multipart](https://github.com/janko/uppy-s3_multipart) | Integration for [Uppy AWS S3 Multipart](https://uppy.io/docs/aws-s3-multipart/) |

data/doc/external/misc.md

@@ -4,14 +4,29 @@ title: Miscellaneous
 
 ## Demos
 
-* [Dropzone demo](https://github.com/codyeatworld/example-shrine-dropzone)
-* [Hanami demo](https://github.com/katafrakt/hanami-shrine-example)
-* [Rails demo](https://github.com/erikdahlstrand/shrine-rails-example)
-* [Resumable uploads demo](https://github.com/shrinerb/shrine-tus-demo)
-* [Roda demo (official)](https://github.com/shrinerb/shrine/tree/master/demo)
-* [ROM & dry-rb demo](https://github.com/shrinerb/shrine-rom/tree/master/demo)
-* [Transloadit demo](https://github.com/shrinerb/shrine-transloadit/tree/master/demo)
+| Demo                                                                                | Description                                      |
+| :---                                                                                | :----------                                      |
+| [Dropzone demo](https://github.com/codyeatworld/example-shrine-dropzone)            | Shows direct upload using [Dropzone.js]          |
+| [Hanami demo](https://github.com/katafrakt/hanami-shrine-example)                   | Shows file attachment in [Hanami]                |
+| [Crop demo](https://github.com/shrinerb/shrine-crop-example)                        | Shows image cropping using [Cropper.js]          |
+| [Rails demo](https://github.com/erikdahlstrand/shrine-rails-example)                | Shows direct upload in [Rails]                   |
+| [Resumable uploads demo](https://github.com/shrinerb/shrine-tus-demo)               | Shows resumable direct upload on [tus]           |
+| [Roda demo (official)](https://github.com/shrinerb/shrine/tree/master/demo)         | Shows direct upload in [Roda]                    |
+| [rom-rb & dry-rb demo](https://github.com/shrinerb/shrine-rom/tree/master/demo)     | Shows file attachment with [rom-rb] and [dry-rb] |
+| [Transloadit demo](https://github.com/shrinerb/shrine-transloadit/tree/master/demo) | Shows file processing using [Transloadit]        |
 
 ## Projects
 
-* [Cortex CMS](https://docs.cortexcms.org)
+| Project                                 | Description                                                             |
+| :------                                 | :----------                                                             |
+| [CortexCMS](https://docs.cortexcms.org) | An open source, enterprise content management and distribution platform |
+
+[Dropzone.js]: https://www.dropzonejs.com/
+[Hanami]: https://hanamirb.org/
+[Cropper.js]: https://github.com/fengyuanchen/cropperjs
+[Rails]: https://rubyonrails.org/
+[tus]: https://tus.io/
+[Roda]: https://roda.jeremyevans.net/
+[rom-rb]: https://rom-rb.org/
+[dry-rb]: https://dry-rb.org/
+[Transloadit]: https://transloadit.com/

data/doc/getting_started.md

@@ -554,7 +554,7 @@ creation:
 gem "image_processing", "~> 1.8"
 ```
 ```rb
-Shrine.plugin :derivatives
+Shrine.plugin :derivatives, create_on_promote: true
 ```
 ```rb
 require "image_processing/mini_magick"
@@ -573,11 +573,7 @@ end
 ```
 ```rb
 photo = Photo.new(image: file)
-
-if photo.valid?
-  photo.image_derivatives! if photo.image_changed? # create derivatives
-  photo.save
-end
+photo.save # automatically creates derivatives on promotion
 ```
 
 You can then retrieve the URL of a processed derivative:
@@ -711,7 +707,7 @@ photo/
 ...
 ```
 
-Buy you can also override `Shrine#generate_location` with a custom
+But you can also override `Shrine#generate_location` with a custom
 implementation, for example:
 
 ```rb
@@ -903,7 +899,7 @@ resumable uploads from scratch, it includes a complete JavaScript example
 
 ## Backgrounding
 
-The [`backgrounding`][backgrounding plugin] allows you to move file promotion
+The [`backgrounding`][backgrounding plugin] plugin allows you to move file promotion
 and deletion into a background job, using the backgrounding library [of your
 choice][Backgrounding Libraries]:
 

data/doc/multiple_files.md

@@ -228,7 +228,7 @@ photos_attributes = album_params[:photos_attributes].to_h.merge(new_photos_attri
 album_attributes  = album_params.merge(photos_attributes: photos_attributes)
 
 # create the album with photos
-Album.create(album_params)
+Album.create(album_attributes)
 ```
 
 In this case you need to make sure your form tag has

data/doc/paperclip.md

@@ -358,13 +358,14 @@ module PaperclipShrineSynchronization
     end
   end
 
-  # If you'll be using a `:prefix` on your Shrine storage, or you're storing
-  # files on the filesystem, make sure to subtract the appropriate part
-  # from the path assigned to `:id`.
   def shrine_attachment_file(attachment)
+    location = attachment.path
+    # if you're storing files on disk, make sure to subtract the absolute path
+    location = location.sub(%r{^#{storage.prefix}/}, "") if storage.prefix
+
     Shrine.uploaded_file(
       storage:  :store,
-      id:       attachment.path,
+      id:       location,
       metadata: {
         "size"      => attachment.size,
         "filename"  => attachment.original_filename,
@@ -377,12 +378,20 @@ module PaperclipShrineSynchronization
   # files on the filesystem, make sure to subtract the appropriate part
   # from the path assigned to `:id`.
   def shrine_style_file(style)
+    location = style.attachment.path(style.name)
+    # if you're storing files on disk, make sure to subtract the absolute path
+    location = location.sub(%r{^#{storage.prefix}/}, "") if storage.prefix
+
     Shrine.uploaded_file(
       storage:  :store,
-      id:       style.attachment.path(style.name),
+      id:       location,
       metadata: {},
     )
   end
+
+  def storage
+    Shrine.storages[:store]
+  end
 end
 ```
 ```rb

data/doc/plugins/add_metadata.md

@@ -34,6 +34,26 @@ uploaded_file.metadata["page_count"] #=> 30
 uploaded_file.page_count #=> 30
 ```
 
+### Skipping nil values
+
+By default, if your block returns `nil` then the `nil` value will be stored into
+metadata. If you do not want to store anything when your block returns nil, you
+can use the `skip_nil: true` option:
+
+```rb
+class PdfUploader < Shrine
+  add_metadata :pages, skip_nil: true do |io|
+    if is_pdf?(io)
+      reader = PDF::Reader.new(io)
+      reader.page_count
+    else
+      # If this is not a PDF, then the pages metadata will not be stored
+      nil
+    end
+  end
+end
+```
+
 ### Multiple values
 
 You can also extract multiple metadata values at once, by using `add_metadata`

data/doc/plugins/atomic_helpers.md

@@ -3,14 +3,48 @@ title: Atomic Helpers
 ---
 
 The [`atomic_helpers`][atomic_helpers] plugin provides API for retrieving and
-persisting attachments in a concurrency-safe way, which is useful when using
-the `backgrounding` plugin. The database plugins (`activerecord` and `sequel`)
-implement atomic promotion and atomic persistence on top of this plugin.
+persisting attachments in a concurrency-safe way, which is especially useful
+when using the `backgrounding` plugin. The database plugins (`activerecord`
+and `sequel`) implement atomic promotion and atomic persistence on top of this
+plugin.
 
 ```rb
 plugin :atomic_helpers
 ```
 
+## Problem Statement
+
+What happens if two different processors (web workers, background jobs,
+command-line executions, whatever) try to edit a shrine attachment
+concurrently? The kinds of edits typically made include: "promoting a file",
+moving it to a different storage and persisting that change in the model;
+adding or changing a derivative; adding or changing a metadata element.
+
+There are two main categories of "race condition":
+
+1. The file could be switched out from under you. If you were promoting a file,
+but some other process has *changed* the attachment, you don't want to
+overwrite it with the promomoted version of the *prior* attacchment. Likewise,
+if you were adding metadata or a derivative, they would be corresponding to a
+certain attachment, and you don't want to accidentally add them to a now changed
+attacchment for which they are inappropriate.
+
+2. Overwriting each other's edits. Since all shrine (meta)data is stored in a
+single JSON hash, standard implementations will write the entire JSON hash at
+once to a rdbms column or other store. If two processes both read in the hash,
+make a change to different keys in it, and then write it back out, the second
+process to write will 'win' and overwrite changes made by the first.
+
+The atomic helpers give you tools to avoid both of these sorts of race
+conditions, under conditions of concurrent editing.
+
+## High-level ORM helpers
+
+If you are using the `sequel` or `activerecord` plugins, they give you two
+higher-level helpers: `atomic_persist` and `atomic_promote`. See the
+[persistence]  documentation for more.
+
+
 ## Retrieving
 
 The `Attacher.retrieve` method provided by the plugin instantiates an attacher
@@ -177,3 +211,7 @@ end
 ```
 
 [atomic_helpers]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/atomic_helpers.rb
+
+[persistence]: https://shrinerb.com/docs/plugins/persistence
+
+[backgrounding]: https://shrinerb.com/docs/plugins/backgrounding

data/doc/plugins/derivatives.md

@@ -2,7 +2,7 @@
 title: Derivatives
 ---
 
-The derivatives plugin allows storing processed files ("derivatives") alongside
+The [`derivatives`][derivatives] plugin allows storing processed files ("derivatives") alongside
 the main attached file. The processed file data will be saved together with the
 main attachment data in the same record attribute.
 
@@ -38,17 +38,9 @@ class ImageUploader < Shrine
 end
 ```
 ```rb
-class Photo < Model(:image_data)
-  include ImageUploader::Attachment(:image)
-end
-```
-```rb
 photo = Photo.new(image: file)
-
-if photo.valid?
-  photo.image_derivatives! if photo.image_changed? # create derivatives
-  photo.save
-end
+photo.image_derivatives! # creates derivatives
+photo.save
 ```
 
 You can then retrieve the URL of a processed derivative:
@@ -205,6 +197,19 @@ attacher.create_derivatives(different_source) # pass a different source file
 attacher.create_derivatives(foo: "bar")       # pass custom options to the processor
 ```
 
+### Create on promote
+
+You can also have derivatives created automatically on promotion:
+
+```rb
+Shrine.plugin :derivatives, create_on_promote: true
+```
+```rb
+attacher.assign(file)
+attacher.finalize # creates derivatives on promotion
+attacher.derivatives #=> { small: ..., medium: ..., large: ... }
+```
+
 ### Naming processors
 
 If you want to have multiple processors for an uploader, you can assign each
@@ -396,7 +401,8 @@ attacher.process_derivatives(:my_processor) # downloads attached file and passes
 
 If you want to use a different source file, you can pass it in to the process
 call. Typically you'd pass a local file on disk. If you pass a
-`Shrine::UploadedFile` object, it will be automatically downloaded to disk.
+`Shrine::UploadedFile` object or another IO-like object, it will be
+automatically downloaded/copied to a local TempFile on disk.
 
 ```rb
 # named processor:
@@ -416,6 +422,20 @@ attacher.file.download do |original|
 end
 ```
 
+If a processor might not always need a local source file, you avoid a
+potentially expensive download/copy by registering the processor with
+`download: false`, in which case the source file will be passed to the
+processor as is.
+
+```rb
+Attacher.derivatives :my_processor, download: false do |source|
+  source #=> Could be File, Shrine::UploadedFile, or other IO-like object
+  shrine_class.with_file(source) do |file|
+    # can force download/copy if necessary with `with_file`,
+  end
+end
+```
+
 ## Adding derivatives
 
 If you already have processed files that you want to save, you can do that with
@@ -459,6 +479,11 @@ For adding a single derivative, you can also use the singular
 attacher.add_derivative(:thumb, thumbnail_file)
 ```
 
+> Note that new derivatives will replace any existing derivatives living under
+the same key, but won't delete them. If this is your case, make sure to save a
+reference to the old derivatives before assigning new ones, and then delete
+them after persisting the change.
+
 Any options passed to `Attacher#add_derivative(s)` will be forwarded to
 [`Attacher#upload_derivatives`](#uploading-derivatives).
 
@@ -567,6 +592,11 @@ attacher.merge_derivatives attacher.upload_derivatives({ nested: { two: two_file
 attacher.derivatives #=> { nested: { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile> } }
 ```
 
+> Note that new derivatives will replace any existing derivatives living under
+the same key, but won't delete them. If this is your case, make sure to save a
+reference to the old derivatives before assigning new ones, and then delete
+them after persisting the change.
+
 The `Attacher#merge_derivatives` method is thread-safe.
 
 ### Setting derivatives
@@ -793,6 +823,7 @@ Or disable logging altogether:
 plugin :derivatives, log_subscriber: nil
 ```
 
+[derivatives]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/derivatives.rb
 [default_url]: https://shrinerb.com/docs/plugins/default_url
 [entity]: https://shrinerb.com/docs/plugins/entity
 [model]: https://shrinerb.com/docs/plugins/model