From 048712dd0a92172f8f99a7c4707493e38181b0b8 Mon Sep 17 00:00:00 2001
From: Alessandro Desantis <desa.alessandro@gmail.com>
Date: Mon, 16 Dec 2019 17:36:30 +0100
Subject: [PATCH] Improve readme wording and formatting

---
 README.md | 36 +++++++++++++++++++-----------------
 1 file changed, 19 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index f5d00d5..3dc674c 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,18 @@
 # SolidusSupport
 
-This gem holds some common functionality for Solidus Extensions.
+This gem contains common runtime functionality for Solidus extensions.
 
-It has some utilities to make it easier to support multiple versions of Solidus.
+If you are looking for development tools instead, see
+[solidus_extension_dev_tools](https://github.com/solidusio-contrib/solidus_extension_dev_tools).
 
 ## Usage
 
 ### `SolidusSupport::Migration`
 
-Rails >= 5 introduced the concept of specifying what rails version your migration was written for, like `ActiveRecord::Migration[5.0]`.
-Not specifying a version is deprecated in Rails 5.0 and removed in rails 5.1.
-This wasn't backported to Rails 4.2, but Rails 4.2 _is_ Rails 4.2. So we provide this helper.
+Rails >= 5 introduced the concept of specifying what Rails version your migration was written for,
+like `ActiveRecord::Migration[5.0]`. Not specifying a version is deprecated in Rails 5.0 and removed
+in Rails 5.1. This wasn't backported to Rails 4.2, so we provide this helper to return the right
+parent class:
 
 ``` ruby
 # On Rails 4.2
@@ -22,15 +24,14 @@ SolidusSupport::Migration[4.2] # same as `ActiveRecord::Migration[4.2]`
 SolidusSupport::Migration[5.0] # same as `ActiveRecord::Migration[5.0]`
 ```
 
-There's no reason to use `SolidusSupport::Migration[5.0]` over `ActiveRecord::Migration[5.0]`, but it is provided.
+There's no reason to use `SolidusSupport::Migration[5.0]` over `ActiveRecord::Migration[5.0]`, but
+it is provided.
 
-### Engine Extensions
+### Engine extensions
 
-This extension provides a module that extends `Rails::Engine` functionalities
-to support loading correctly the decorators class created into an extension
-both for development and production enviroments.
-
-To use it just include the provided module in the Engine as follow:
+This extension provides a module that decorates `Rails::Engine` to seamlessly support autoloading
+decorators both with the classic autoloader and with Zeitwerk on Rails 6. In order to use it, just
+include the provided module in your `Engine` class:
 
 ```ruby
 module SolidusExtensionName
@@ -38,13 +39,13 @@ module SolidusExtensionName
     engine_name 'solidus_extension_name'
 
     include SolidusSupport::EngineExtensions::Decorators
+
     # ...
   end
 end
 ```
 
-To make it work, be sure to remove the previous implementation from the
-Engine, that should be something like:
+If needed, also ensure to remove the original implementation of `.activate`:
 
 ```ruby
 def self.activate
@@ -58,9 +59,10 @@ config.to_prepare(&method(:activate).to_proc)
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new
+version, update the version number in `version.rb`, and then run `bundle exec rake release`, which
+will create a git tag for the version, push git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
 
 ## Contributing