Merge branch 'docs/upgrades-for-background-migrations' into 'master'

Update the guides for updating GitLab and adding background migrations

See merge request !13284

2 files changed, 16 insertions, 8 deletions

diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md
index e67db9ff142..f83a60e49e8 100644
--- a/doc/development/background_migrations.md
+++ b/doc/development/background_migrations.md
@@ -7,6 +7,11 @@ storing data in a single JSON column the data is stored in a separate table.
 
 ## When To Use Background Migrations
 
+>**Note:**
+When adding background migrations _you must_ make sure they are announced in the
+monthly release post along with an estimate of how long it will take to complete
+the migrations.
+
 In the vast majority of cases you will want to use a regular Rails migration
 instead. Background migrations should _only_ be used when migrating _data_ in
 tables that have so many rows this process would take hours when performed in a
@@ -91,6 +96,10 @@ BackgroundMigrationWorker.perform_bulk_in(5.minutes, jobs)
 
 ## Cleaning Up
 
+>**Note:**
+Cleaning up any remaining background migrations _must_ be done in either a major
+or minor release, you _must not_ do this in a patch release.
+
 Because background migrations can take a long time you can't immediately clean
 things up after scheduling them. For example, you can't drop a column that's
 used in the migration process as this would cause jobs to fail. This means that
diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md
index 161d2544169..9b8ab5da74e 100644
--- a/doc/development/migration_style_guide.md
+++ b/doc/development/migration_style_guide.md
@@ -35,12 +35,11 @@ Please don't depend on GitLab-specific code since it can change in future
 versions. If needed copy-paste GitLab code into the migration to make it forward
 compatible.
 
-## Commit Guidelines
+## Schema Changes
 
-Each migration **must** be added in its own commit with a descriptive commit
-message. If a commit adds a migration it _should only_ include the migration and
-any corresponding changes to `db/schema.rb`. This makes it easy to revert a
-database migration without accidentally reverting other changes.
+Migrations that make changes to the database schema (e.g. adding a column) can
+only be added in the monthly release, patch releases may only contain data
+migrations _unless_ schema changes are absolutely required to solve a problem.
 
 ## Downtime Tagging
 
@@ -224,9 +223,9 @@ add_column(:projects, :foo, :integer, default: 10, limit: 8)
 
 ## Timestamp column type
 
-By default, Rails uses the `timestamp` data type that stores timestamp data without timezone information.        
-The `timestamp` data type is used by calling either the `add_timestamps` or the `timestamps` method.       
-Also Rails converts the `:datetime` data type to the `timestamp` one.        
+By default, Rails uses the `timestamp` data type that stores timestamp data without timezone information.
+The `timestamp` data type is used by calling either the `add_timestamps` or the `timestamps` method.
+Also Rails converts the `:datetime` data type to the `timestamp` one.
 
 Example: