docs/migrating.md in elabs-3.0.0 vs docs/migrating.md in elabs-4.0.0

@@ -1,6 +1,57 @@
 # Migration guide
 
+## From 3.x to 4.0.0
+
+First of all, read the changelog for the 4.0.0 release.
+
+Use a version control system to manage the changes and the overrides you
+made in your own application.
+
+- Add the Commonmarker gem: `gem 'commonmarker'` if you use the default
+  views
+- Update the base configuration (initializer, languages, ...):
+  `rails g elabs:install` and accept to override everything. Then check
+  changes
+- Apply the last migrations: `rake elabs:install:migrations` then
+  `rails db:migrate`
+
+Don't forget to rebuild the assets...
+
+If you have existing content you need to redirect you can use a runner
+like this one:
+
+```rb
+# Example for Apache
+# Uncomment if you need to enable RewriteEngine (mod_rewrite is required)
+puts "# RewriteEngine  on"
+
+[
+    { model: Elabs::Language, subs: %w[albums articles notes projects uploads] },
+    { model: Elabs::License, subs: %w[albums articles notes projects uploads] },
+    { model: Elabs::Tag, subs: %w[albums articles notes projects uploads] },
+    { model: Elabs::User, subs: %w[albums articles notes projects uploads] },
+    { model: Elabs::Album, subs: [] },
+    { model: Elabs::Article, subs: [] },
+    { model: Elabs::Note, subs: [] },
+    { model: Elabs::Project, subs: %w[albums articles notes uploads] },
+    { model: Elabs::Upload, subs: [] },
+].each do |config|
+  slug_field = config[:model]::SLUG_FIELD
+  endpoint   = config[:model].to_s.demodulize.tableize
+  puts '# Entities redirection'
+  config[:model].all.each do |record|
+    # Entity
+    puts "Redirect 301 /#{endpoint}/#{record.id} /#{endpoint}/#{record.send(slug_field)}"
+
+    # Nested resources
+    config[:subs].each do |sub|
+      puts "Redirect 301 /#{endpoint}/#{record.id}/#{sub} /#{endpoint}/#{record.send(slug_field)}/#{sub}"
+    end
+  end
+end
+```
+
 ## From 2.x to 3.0.0
 
 First of all, read the changelog for the 3.0.0 release
 
 - Update the translations: `rails g elabs:install` and accept to override