Add latest changes from gitlab-org/gitlab@master

2 files changed, 27 insertions, 7 deletions

diff --git a/doc/development/database_review.md b/doc/development/database_review.md
index f2db0ab4fd5..aa7ebb3756f 100644
--- a/doc/development/database_review.md
+++ b/doc/development/database_review.md
@@ -74,12 +74,12 @@ the following preparations into account.
 
 #### Preparation when adding migrations
 
-- Ensure `db/structure.sql` is updated.
+- Ensure `db/structure.sql` is updated as [documented](migration_style_guide.md#schema-changes).
 - Make migrations reversible by using the `change` method or include a `down` method when using `up`.
   - Include either a rollback procedure or describe how to rollback changes.
-- Add the output of both migrating and rolling back for all migrations into the MR description
-  - Ensure the down method reverts the changes in `db/structure.sql`
-  - Update the migration output whenever you modify the migrations during the review process
+- Add the output of both migrating and rolling back for all migrations into the MR description.
+  - Ensure the down method reverts the changes in `db/structure.sql`.
+  - Update the migration output whenever you modify the migrations during the review process.
 - Add tests for the migration in `spec/migrations` if necessary. See [Testing Rails migrations at GitLab](testing_guide/testing_migrations_guide.md) for more details.
 - When [high-traffic](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/migration_helpers.rb#L12) tables are involved in the migration, use the [`with_lock_retries`](migration_style_guide.md#retry-mechanism-when-acquiring-database-locks) helper method. Review the relevant [examples in our documentation](migration_style_guide.md#examples) for use cases and solutions.
 - Ensure RuboCop checks are not disabled unless there's a valid reason to.
diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md
index 3e993243855..371fdf8b7f0 100644
--- a/doc/development/migration_style_guide.md
+++ b/doc/development/migration_style_guide.md
@@ -35,9 +35,29 @@ and post-deployment migrations (`db/post_migrate`) are run after the deployment
 
 ## Schema 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.
+Changes to the schema should be commited to `db/structure.sql`. This
+file is automatically generated by Rails, so you normally should not
+edit this file by hand. If your migration is adding a column to a
+table, that column will be added at the bottom. Please do not reorder
+columns manually for existing tables as this will cause confusing to
+other people using `db/structure.sql` generated by Rails.
+
+When your local database in your GDK is diverging from the schema from
+`master` it might be hard to cleanly commit the schema changes to
+Git. In that case you can use the `script/regenerate-schema` script to
+regenerate a clean `db/structure.sql` for the migrations you're
+adding. This script will apply all migrations found in `db/migrate`
+or `db/post_migrate`, so if there are any migrations you don't want to
+commit to the schema, rename or remove them. If your branch is not
+targetting `master` you can set the `TARGET` environment variable.
+
+```sh
+# Regenerate schema against `master`
+bin/regenerate-schema
+
+# Regenerate schema against `12-9-stable-ee`
+TARGET=12-9-stable-ee bin/regenerate-schema
+```
 
 ## What Requires Downtime?