Merge branch 'migration-reversibility-docs' into 'master'

Add info to migration style guide on reversibility

See merge request gitlab-org/gitlab!25098

doc/development/migration_style_guide.md

@@ -89,6 +89,21 @@ be possible to downgrade in case of a vulnerability or bugs.
 In your migration, add a comment describing how the reversibility of the
 migration was tested.
 
+Some migrations cannot be reversed. For example, some data migrations can't be
+reversed because we lose information about the state of the database before the migration.
+You should still create a `down` method with a comment, explaining why
+the changes performed by the `up` method can't be reversed, so that the
+migration itself can be reversed, even if the changes performed during the migration
+can't be reversed:
+
+```ruby
+def down
+  # no-op
+
+  # comment explaining why changes performed by `up` cannot be reversed.
+end
+```
+
 ## Atomicity
 
 By default, migrations are single transaction. That is, a transaction is opened