diff options
author | Sytse Sijbrandij <sytse@gitlab.com> | 2015-05-11 17:43:26 +0300 |
---|---|---|
committer | Sytse Sijbrandij <sytse@gitlab.com> | 2015-05-11 17:43:26 +0300 |
commit | 426fa2af912c2ac56e0c70f79c9f175031465a3b (patch) | |
tree | 84bcc24d7f470cabe0648443bae02609302dc542 /doc/development | |
parent | 396aba5e1032ac3f94dca85636ffa069c44e2360 (diff) | |
parent | 6a6047f80c63f55e70a3d66e70a221f319cab0d2 (diff) |
Merge branch 'migration-style-guide' into 'master'
Migration Style Guide
Fixes #2305
See merge request !1821
Diffstat (limited to 'doc/development')
-rw-r--r-- | doc/development/README.md | 3 | ||||
-rw-r--r-- | doc/development/migration_style_guide.md | 39 |
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. |