shrine 3.0.0.rc → 3.0.0

data/doc/release_notes/1.0.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 1.0.0
+---
+
 # Backwards compatibility
 
 * The `delete_invalid` plugin was removed, because it was unstable since next

data/doc/release_notes/1.1.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 1.1.0
+---
+
 # New plugins
 
 * The `download_endpoint` plugin has been added, which allows downloading files

data/doc/release_notes/1.2.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 1.2.0
+---
+
 New features
 ============
 

data/doc/release_notes/1.3.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 1.3.0
+---
+
 New features
 ============
 

data/doc/release_notes/1.4.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 1.4.0
+---
+
 New features
 ============
 

data/doc/release_notes/1.4.1.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 1.4.1
+---
+
 Regressions
 ===========
 

data/doc/release_notes/1.4.2.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 1.4.2
+---
+
 Regressions
 ===========
 

data/doc/release_notes/2.0.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.0.0
+---
+
 Backwards compatibility
 =======================
 

data/doc/release_notes/2.0.1.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.0.1
+---
+
 Regressions
 ===========
 

data/doc/release_notes/2.1.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.1.0
+---
+
 Improvements
 ============
 

data/doc/release_notes/2.1.1.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.1.1
+---
+
 Regressions
 ===========
 

data/doc/release_notes/2.10.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.10.0
+---
+
 ## New features
 
 * The `:mini_magick` analyzer has been added to the `store_dimensions` plugin,

data/doc/release_notes/2.10.1.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.10.1
+---
+
 ## Regressions
 
 * Determining MIME type from file extension (using `:mime_types` or

data/doc/release_notes/2.11.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.11.0
+---
+
 ## New features
 
 * `Shrine::UploadedFile#stream` has been added for streaming the uploaded

data/doc/release_notes/2.12.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.12.0
+---
+
 ## New features
 
 * The `Shrine::Attacher#assign_remote_url` method has been added, which acts the

data/doc/release_notes/2.13.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.13.0
+---
+
 ## New features
 
 * The S3 object URLs can now be signed with a custom signer. This enables

data/doc/release_notes/2.14.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.14.0
+---
+
 ## New features
 
 * `Shrine::Storage::S3` now accepts a `:client` option for specifying an AWS
@@ -274,5 +278,5 @@
   `#download_url`). If you've are currently overriding any of these private
   methods, you'll need to update your code.
 
-[Retrieving Uploads]: /doc/retrieving_uploads.md#readme
+[Retrieving Uploads]: https://shrinerb.com/docs/retrieving-uploads
 [content_disposition]: https://github.com/shrinerb/content_disposition

data/doc/release_notes/2.15.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.15.0
+---
+
 ## New features
 
 * The [`derivation_endpoint`][derivation_endpoint] plugin has been added, which
@@ -74,9 +78,9 @@
   relying on multiple invocations returning the same object, you will need to
   modify your code.
 
-[derivation_endpoint]: /doc/plugins/derivation_endpoint.md#readme
-[CDN host]: /doc/plugins/derivation_endpoint.md#host
-[`Content-Type`]: /doc/plugins/derivation_endpoint.md#content-type
-[`Content-Disposition`]: /doc/plugins/derivation_endpoint.md#content-disposition
-[URL expiration]: /doc/plugins/derivation_endpoint.md#expiration
-[uploading]: /doc/plugins/derivation_endpoint.md#uploading
+[derivation_endpoint]: https://shrinerb.com/docs/plugins/derivation_endpoint
+[CDN host]: https://shrinerb.com/docs/plugins/derivation_endpoint#host
+[`Content-Type`]: https://shrinerb.com/docs/plugins/derivation_endpoint#content-type
+[`Content-Disposition`]: https://shrinerb.com/docs/plugins/derivation_endpoint#content-disposition
+[URL expiration]: https://shrinerb.com/docs/plugins/derivation_endpoint#expiration
+[uploading]: https://shrinerb.com/docs/plugins/derivation_endpoint#uploading

data/doc/release_notes/2.16.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.16.0
+---
+
 ## New Features
 
 * The `:download_options` option has been added to the `download_endpoint`

data/doc/release_notes/2.17.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.17.0
+---
+
 ## New features
 
 * The `download_endpoint` plugin now accepts ad-hoc options when creating the

data/doc/release_notes/2.18.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.18.0
+---
+
 ## New features
 
 * Added `Shrine.upload_response` to `upload_endpoint` plugin for handling

data/doc/release_notes/2.19.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.19.0
+---
+
 ## New features
 
 * A new `instrumentation` plugin has been added. It sends and logs events for
@@ -12,7 +16,7 @@
   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}
@@ -228,8 +232,8 @@
   `FileSystem#upload`. This means that the `#move` && `#movable?` methods are
   not part of the storage abstraction anymore.
 
-* The `backup` plugin has been deprecated over [mirroring uploads] via the
-  `instrumentation` plugin.
+* The `backup` plugin has been deprecated (a new `mirroring` plugin will get
+  added in 3.0).
 
 * The `copy` plugin has been deprecated.
 
@@ -260,4 +264,3 @@
 
 [ActiveSupport::Notifications]: https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html
 [dry-monitor]: https://github.com/dry-rb/dry-monitor
-[mirroring uploads]: https://github.com/shrinerb/shrine/wiki/Mirroring-Uploads

data/doc/release_notes/2.2.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.2.0
+---
+
 ## New plugins
 
 * The processing plugin has been added for declaratively defining processing

data/doc/release_notes/2.3.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.3.0
+---
+
 ## New plugins
 
 * The `copy` plugin has been added for copying files from one record to

data/doc/release_notes/2.3.1.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.3.1
+---
+
 Regressions
 ===========
 

data/doc/release_notes/2.4.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.4.0
+---
+
 ## New features
 
 * The `default_url_options` plugin accepts a block for dynamically generating

data/doc/release_notes/2.4.1.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.4.1
+---
+
 ## Regressions
 
 * Prior to version 2.4.0, the conversion of uploaded file data to JSON was

data/doc/release_notes/2.5.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.5.0
+---
+
 ## New features
 
 * The `add_metadata` plugin has been extended to enable extracting and saving

data/doc/release_notes/2.6.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.6.0
+---
+
 ## New plugins
 
 * Added `signature` plugin which allows you to calculate a

data/doc/release_notes/2.6.1.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.6.1
+---
+
 ## Bug fixes
 
 * When `download_endpoint` streams file content into the response body, with

data/doc/release_notes/2.7.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.7.0
+---
+
 ## New Plugins
 
 * The `direct_upload` plugin has been split into `upload_endpoint` and

data/doc/release_notes/2.8.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.9.0
+---
+
 ## New Features
 
 * The `rack_response` plugin now supports [range requests] via the `:range`

data/doc/release_notes/2.9.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.9.0
+---
+
 ## New Plugins
 
 * The `infer_extension` plugin has been added, which automatically infers

data/doc/release_notes/3.0.0.md

@@ -1,4 +1,6 @@
-# Shrine 3.0.0
+---
+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
@@ -35,9 +37,82 @@ how to upgrade.
   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
-  - possibility of storing processed files on a separate storage
+
+    ```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
+    ```
+
+  - possibility of uploading processed files to different storage
+
+    ```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
+
+    photo.image_derivatives!
+    photo.image_derivatives[:large].storage_key #=> :other_store
+    ```
 
 * The [`Shrine::Attacher`][attacher] class has been rewritten and can now be
   used without models:
@@ -113,7 +188,7 @@ how to upgrade.
   ```
 
 * The new [`model`][model] plugin adds support for mutable structs, which is
-  used for `activerecord` and `sequel` plugins.
+  used by `activerecord` and `sequel` plugins.
 
   ```rb
   Shrine.plugin :model
@@ -281,6 +356,8 @@ how to upgrade.
   attacher.file #=> #<Shrine::UploadedFile @id="..." @storage_key=:cache ...>
   ```
 
+## Other features
+
 * Model file assignment can now be configured to upload directly to permanent
   storage.
 
@@ -292,8 +369,6 @@ how to upgrade.
   photo.image.storage_key #=> :store (permanent storage)
   ```
 
-## Other features
-
 * New `Shrine.download_response` method has been added to the
   `download_endpoint` plugin for generating file response from the controller.
 
@@ -383,6 +458,13 @@ how to upgrade.
 * New `Derivation#opened` method has been added for retrieving an opened
   derivative in `derivation_endpoint` plugin.
 
+* New `Storage#delete_prefixed` method has been added for deleting all files
+  in specified directory.
+
+  ```rb
+  storage.delete_prefixed("some_directory/")
+  ```
+
 ## Performance improvements
 
 * The attached file is now parsed and loaded from record column only once,
@@ -454,6 +536,15 @@ how to upgrade.
 
 * The `down` dependency has been updated to `~> 5.0`.
 
+* The `Shrine::Attachment[]` method has been added as an alternative syntax for
+  creating attachment modules.
+
+  ```rb
+  class Photo
+    include ImageUploader::Attachment[:image]
+  end
+  ```
+
 ### Plugin improvements
 
 * The `activerecord` plugin now works with Active Record 3.
@@ -461,6 +552,10 @@ how to upgrade.
 * Callback code from `activerecord` and `sequel` plugin has been moved into
   attacher methods, allowing the user to override them.
 
+  - `Attacher#(activerecord|sequel)_before_save`
+  - `Attacher#(activerecord|sequel)_after_save`
+  - `Attacher#(activerecord|sequel)_after_destroy`
+
 * The `url_options` plugin now allows you to override URL options by deleting
   them.
 
@@ -534,6 +629,9 @@ how to upgrade.
   # "blog_post/aa357797-5845-451b-8662-08eecdc9f762/image/493g82jf23.jpg"
   ```
 
+* You can now load multiple persistence plugins simulatenously, and the correct
+  one will be activated during persistence.
+
 ## Backwards compatibility
 
 ### Plugin deprecation and removal
@@ -559,25 +657,11 @@ how to upgrade.
 
 ### Attacher API
 
-* The `Attacher.new` method now only accepts a hash of options.
-
-  ```rb
-  # this doesn't work anymore
-  Shrine::Attacher.new(photo, :image) # ~> ArgumentError: invalid number of arguments
-
-  # this should be used instead
-  Shrine::Attacher.from_model(photo, :image)
-  ```
-
-* The attacher won't detect direct data attribute changes anymore. If you're
-  updating the data attribute and are expecting to see the change applied to
-  the attacher, you'll need to call `Attacher#reload`.
+* The `Attacher.new` method now only accepts a hash of options, use
+  `Attacher.from_model` for initializing from a model.
 
-  ```rb
-  attacher = photo.image_attacher
-  photo.image_data = '...'
-  attacher.reload
-  ```
+* If you're changing the attachment data column directly, you'll now need to
+  call `Attacher#reload` to make the attacher reflect those changes.
 
 * The `Attacher#promote` method now only saves the promoted file in memory,
   it doesn't persist the changes.
@@ -768,9 +852,6 @@ how to upgrade.
 
   - The `Derivation#upload` method now closes the uploaded file.
 
-  - Uploader deleting the uploaded derivative isn't supported anymore (e.g.
-    `delete_raw` plugin).
-
   - The `derivation.upload` instrumentation event payload now includes only
     `:derivation` key.
 
@@ -867,16 +948,17 @@ how to upgrade.
 
   - The `:callbacks` plugin option has been renamed to `:hooks`.
 
-[derivatives]: /doc/plugins/derivatives.md#readme
-[versions]: /doc/plugins/versions.md#readme
-[backgrounding]: /doc/plugins/backgrounding.md#readme
+[derivatives]: https://shrinerb.com/docs/plugins/derivatives
+[versions]: https://shrinerb.com/docs/plugins/versions
+[backgrounding]: https://shrinerb.com/docs/plugins/backgrounding
 [shrine-memory]: https://github.com/shrinerb/shrine-memory
-[atomic_helpers]: /doc/plugins/atomic_helpers.md#readme
-[attacher]: /doc/attacher.md#readme
-[column]: /doc/plugins/column.md#readme
-[entity]: /doc/plugins/entity.md#readme
-[model]: /doc/plugins/model.md#readme
-[persistence]: /doc/plugins/persistence.md#readme
-[mirroring]: /doc/plugins/mirroring.md#readme
-[form_assign]: /doc/plugins/form_assign.md#readme
-[Upgrading to Shrine 3.x]: /doc/upgrading_to_3.md#readme
+[atomic_helpers]: https://shrinerb.com/docs/plugins/atomic_helpers
+[attacher]: https://shrinerb.com/docs/attacher
+[column]: https://shrinerb.com/docs/plugins/column
+[entity]: https://shrinerb.com/docs/plugins/entity
+[model]: https://shrinerb.com/docs/plugins/model
+[persistence]: https://shrinerb.com/docs/plugins/persistence
+[mirroring]: https://shrinerb.com/docs/plugins/mirroring
+[form_assign]: https://shrinerb.com/docs/plugins/form_assign
+[multi_cache]: https://shrinerb.com/docs/plugins/multi_cache
+[Upgrading to Shrine 3.x]: https://shrinerb.com/docs/upgrading-to-3