Add a migration guide

README.md

@@ -9,22 +9,22 @@ An ember-cli addon to automatically generate resized images at build-time, optim
 
 ## Key Features
 
-🌇 Supports basic PNG and JPEG formats, as well as next-gen [**WebP**](https://developer.mozilla.org/en-US/Web/Media/Formats/Image_types#webp) and [**AVIF**](https://developer.mozilla.org/en-US/Web/Media/Formats/Image_types#avif), for best image quality at low file sizes.
+🌇  Supports basic PNG and JPEG formats, as well as next-gen [**WebP**](https://developer.mozilla.org/en-US/Web/Media/Formats/Image_types#webp) and [**AVIF**](https://developer.mozilla.org/en-US/Web/Media/Formats/Image_types#avif), for best image quality at low file sizes.
 
-🏎 Super **fast image processing**, thanks to the awesome [sharp](https://github.com/lovell/sharp) library.
+🏎  Super **fast image processing**, thanks to the awesome [sharp](https://github.com/lovell/sharp) library.
 
-📱 Layout modes for **fixed sizes** (with `1x` and `2x` image variants) as well as **responsive layouts** (`srcset` with optimized image sizes across all devices). 
+📱  Layout modes for **fixed sizes** (with `1x` and `2x` image variants) as well as **responsive layouts** (`srcset` with optimized image sizes across all devices). 
 
-💯 **Lazy rendering** by default, with optimized `content-visibility` and `decoding` settings and optimized markup, to prevent [**CLS**](https://web.dev/cls/) (*Cumulative Layout Shift*), a core [Web Vital](https://web.dev/vitals/) and [Lighthouse](https://developers.google.com/web/tools/lighthouse) metric.
+💯  **Lazy rendering** by default, with optimized `content-visibility` and `decoding` settings and optimized markup, to prevent [**CLS**](https://web.dev/cls/) (*Cumulative Layout Shift*), a core [Web Vital](https://web.dev/vitals/) and [Lighthouse](https://developers.google.com/web/tools/lighthouse) metric.
 
-⏳ Supports advanced **LQIP** (*Low Quality Image Placeholder*) techniques to show a preview while loading, using different configurable strategies
+⏳  Supports advanced **LQIP** (*Low Quality Image Placeholder*) techniques to show a preview while loading, using different configurable strategies
 like a blurry low-res image, [BlurHash](https://blurha.sh/) or a simple dominant color. 
 
-✨ Octane-based, written mostly in **TypeScript**, using **Glimmer** components, supporting [FastBoot](https://ember-fastboot.com/) and [Embroider](https://github.com/embroider-build/embroider), and fully tested.
+✨  Octane-based, written mostly in **TypeScript**, using **Glimmer** components, supporting [FastBoot](https://ember-fastboot.com/) and [Embroider](https://github.com/embroider-build/embroider), and fully tested.
 
-️⚙ Flexible configuration options
+️⚙  Flexible configuration options
 
-Advanced optimization techniques inspired amongst others by [this blog post](https://www.industrialempathy.com/posts/image-optimizations/).
+Advanced optimization techniques inspired amongst others by the blog post [Maximally optimizing image loading for the web in 2021](https://www.industrialempathy.com/posts/image-optimizations/).
 
 Compatibility
 ------------------------------------------------------------------------------
@@ -36,6 +36,10 @@ Compatibility
 
 ## Getting started
 
+### Migration
+
+If you were previously using an older version (<2.x) of this addon, there is a [Migration Guide](docs/MIGRATION.md) to help you go through the (many!) breaking changes.
+
 ### Install in ember-cli application
 
 In your application's directory:

docs/MIGRATION.md

@@ -0,0 +1,37 @@
+# Migrating from 0.x/1.x to 2.x
+
+## Config
+
+* The configuration of the addon moved from `config/environment.js` to `ember-cli-build.js`.
+* The configuration now expects an object with an `images` key. So instead of `[{ // image options },...]` you would transform that to `{ images: [{ // image options },...]}`.
+* the `sourceDir` and `destinationDir` image options have been removed in favor of an `include` glob pattern (array). So transform `sourceDir: 'some/path'` to `include: ['some/path/*']`.
+* the `recursive` option has been removed. To process images in sub folders, use the `**` glob pattern: `include: ['some/path/**/*']`.
+* the `extensions` option has been removed. To process only files with a certain extension you can integration the extension into the glob pattern: `include: ['some/path/*.jpg']`.
+* rename your `supportedWidths` option to just `widths`.
+
+## `<ResponsiveImage>` Component
+
+* the `@image` argument has been renamed to `@src`, and it now refers to the image using its full path (just like a normal `<img src="...">` does!).
+* the rendered markup now has the `<img>` element wrapped in a `<picture>`. In most cases this should not be noticeable, but when your CSS is sensitive to the nesting like for example with a flexbox layout or a direct child selector `.some > img` the CSS might be applied differently now.
+* The image is loaded lazily by default, using the browser's native capabilites (if supported). This can cause difference in loading timings, eventually leading to *worse* performance metrics (like FCP/LCP) when an image is clearly above the fold, but the browser needs to wait for the first page layout to happen before it can decide weather it needs to be loaded. So for images *above* the fold it is recommended to set loading to "eager": `<ResponsiveImage @src="some/image.jpg" loading="eager"/>`.
+* The image will have responsive CSS applied by default (unless you make it a "fixed" layout, see the main docs), so check if that causes any layout changes.
+
+## Other changes
+
+* the `<ResponsiveBackground>` has been removed (as its capabilities to detect the optimal image size and format were too limited anyway). You can render a normal `<ResponsiveImage>` instead and make it behave like a background using CSS like in this example:
+```css
+img {
+  display: block;
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  z-index: -1;
+  object-fit: cover;
+}
+```
+* The previous mixins have been removed, as they don't fit well into the modern Octane paradigms like native classes.
+* The `setupResponsiveImage()` test helper is not needed and not available anymore.
+* The addon now integrates powerful LQIP (low quality image placeholders) techniques. These are not enabled by default, so no changes are expected. But be sure to look into these new options that you might want to enable.
+