diff options
author | Job van der Voort <jobvandervoort@gmail.com> | 2015-05-11 16:09:36 +0300 |
---|---|---|
committer | Job van der Voort <jobvandervoort@gmail.com> | 2015-05-11 16:09:36 +0300 |
commit | 6a6047f80c63f55e70a3d66e70a221f319cab0d2 (patch) | |
tree | 84bcc24d7f470cabe0648443bae02609302dc542 /doc/development/migration_style_guide.md | |
parent | 396aba5e1032ac3f94dca85636ffa069c44e2360 (diff) |
create migration style guide. Fixes #2305
Diffstat (limited to 'doc/development/migration_style_guide.md')
-rw-r--r-- | doc/development/migration_style_guide.md | 39 |
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. |