Add documentation about the migration hack

config/initializers/0_duplicate_migrations.rb

@@ -1,3 +1,17 @@
+# Some migrations have been present in glitch-soc for a long time and have then
+# been merged in upstream Mastodon, under a different version number.
+#
+# This puts us in an uneasy situation in which if we remove upstream's
+# migration file, people migrating from upstream will end up having a conflict
+# with their already-ran migration.
+#
+# On the other hand, if we keep upstream's migration and remove our own,
+# any current glitch-soc user will have a conflict during migration.
+#
+# For lack of a better solution, as those migrations are indeed identical,
+# we decided monkey-patching Rails' Migrator to completely ignore the duplicate,
+# keeping only the one that has run, or an arbitrary one.
+
 ALLOWED_DUPLICATES = [20180410220657, 20180831171112].freeze
 
 module ActiveRecord

db/migrate/20180410220657_create_bookmarks.rb

@@ -1,3 +1,6 @@
+# This migration is a duplicate of 20180831171112 and may get ignored, see
+# config/initializers/0_duplicate_migrations.rb
+
 class CreateBookmarks < ActiveRecord::Migration[5.1]
   def change
     create_table :bookmarks do |t|
@@ -7,8 +10,11 @@ class CreateBookmarks < ActiveRecord::Migration[5.1]
       t.timestamps
     end
 
-    safety_assured { add_foreign_key :bookmarks, :accounts, column: :account_id, on_delete: :cascade }
-    safety_assured { add_foreign_key :bookmarks, :statuses, column: :status_id, on_delete: :cascade }
+    safety_assured do
+      add_foreign_key :bookmarks, :accounts, column: :account_id, on_delete: :cascade
+      add_foreign_key :bookmarks, :statuses, column: :status_id, on_delete: :cascade
+    end
+
     add_index :bookmarks, [:account_id, :status_id], unique: true
   end
 end

db/migrate/20180831171112_create_bookmarks.rb

@@ -1,3 +1,6 @@
+# This migration is a duplicate of 20180410220657 and may get ignored, see
+# config/initializers/0_duplicate_migrations.rb
+
 class CreateBookmarks < ActiveRecord::Migration[5.1]
   def change
     create_table :bookmarks do |t|