create migration style guide. Fixes #2305

1 files changed, 39 insertions, 0 deletions

diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md
new file mode 100644
index 00000000000..db2d8b99721
--- /dev/null
+++ b/doc/development/migration_style_guide.md
@@ -0,0 +1,39 @@
+# Migration Style Guide
+
+When writing migrations for GitLab, you have to take into account that
+these will be ran by thousands of organizations of all sizes, some with
+many years of data in their database.
+
+In addition, having to take a server offline for a an upgrade small or big is
+a big burden for most organizations. For this reason it is important that your
+migrations are written carefully and adhere to the style guide below.
+
+When writing your migrations, also consider that databases might have stale data
+or inconsistencies and guard for that. Try to make as little assumptions as possible
+about the state of the database.
+
+## Comments in the migration
+
+Each migration you write needs to have the two following pieces of information
+as comments.
+
+### Online, Offline, errors?
+
+First, you need to provide information on whether the migration can be applied:
+
+1. online without errors (works on previous version and new one)
+2. online with errors on old instances after migrating
+3. online with errors on new instances while migrating
+4. offline (needs to happen without app servers to prevent db corruption)
+
+It is always preferable to have a migration run online. If you expect the migration
+to take particularly long (for instance, if it loops through all notes),
+this is valuable information to add.
+
+### Reversibility
+
+Your migration should be reversible. This is very important, as it should
+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.