create migration style guide. Fixes #2305

2 files changed, 41 insertions, 1 deletions

diff --git a/doc/development/README.md b/doc/development/README.md
index d5d264be19d..16df0b40c47 100644
--- a/doc/development/README.md
+++ b/doc/development/README.md
@@ -1,4 +1,4 @@
-# Development 
+# Development
 
 - [Architecture](architecture.md) of GitLab
 - [Shell commands](shell_commands.md) in the GitLab codebase
@@ -6,3 +6,4 @@
 - [CI setup](ci_setup.md) for testing GitLab
 - [Sidekiq debugging](sidekiq_debugging.md)
 - [UI guide](ui_guide.md) for building GitLab with existing css styles and elements
+- [Migration Style Guide](migration_style_guide.md) for creating safe migrations
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.