create migration style guide. Fixes #2305

CONTRIBUTING.md

@@ -63,7 +63,7 @@ Merge requests can be filed either at [gitlab.com](https://gitlab.com/gitlab-org
 
 If you are new to GitLab development (or web development in general), search for the label `easyfix` ([gitlab.com](https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=easyfix), [github](https://github.com/gitlabhq/gitlabhq/labels/easyfix)). Those are issues easy to fix, marked by the GitLab core-team. If you are unsure how to proceed but want to help, mention one of the core-team members to give you a hint.
 
-To start with GitLab download the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit) and see [Development section](doc/development/README.md) in the help file. 
+To start with GitLab download the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit) and see [Development section](doc/development/README.md) in the help file.
 
 ### Merge request guidelines
 
@@ -161,6 +161,7 @@ If you add a dependency in GitLab (such as an operating system package) please c
 1.  [Shell commands](doc/development/shell_commands.md) created by GitLab contributors to enhance security
 1.  [Markdown](http://www.cirosantilli.com/markdown-styleguide)
 1.  Interface text should be written subjectively instead of objectively. It should be the gitlab core team addressing a person. It should be written in present time and never use past tense (has been/was). For example instead of "prohibited this user from being saved due to the following errors:" the text should be "sorry, we could not create your account because:". Also these [excellent writing guidelines](https://github.com/NARKOZ/guides#writing).
+1. [Migrations](doc/development/migration_style_guide.md)
 
 This is also the style used by linting tools such as [RuboCop](https://github.com/bbatsov/rubocop), [PullReview](https://www.pullreview.com/) and [Hound CI](https://houndci.com).
 

doc/development/README.md

-# 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

doc/development/migration_style_guide.md

+# 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.