Merge branch 'bbodenmiller-master-patch-00681' into 'master'

Improve database migration guide

See merge request gitlab-org/gitlab!59721

doc/development/database_review.md

@@ -43,7 +43,7 @@ If your merge request description does not include these items, the review will
 
 If new migrations are introduced, in the MR **you are required to provide**:
 
-- The output of both migrating and rolling back for all migrations
+- The output of both migrating (`db:migrate`) and rolling back (`db:rollback`) for all migrations.
 
 If new queries have been introduced or existing queries have been updated, **you are required to provide**:
 
@@ -104,7 +104,7 @@ the following preparations into account.
 `db/schema_migrations` were added or removed.
 - 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.
+- Add the output of both migrating (`db:migrate`) and rolling back (`db:rollback`) 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.

doc/development/migration_style_guide.md

@@ -19,8 +19,8 @@ Migrations are **not** allowed to require GitLab installations to be taken
 offline ever. Migrations always must be written in such a way to avoid
 downtime. In the past we had a process for defining migrations that allowed for
 downtime by setting a `DOWNTIME` constant. You may see this when looking at
-older migrations. This process was in place for 4 years without every being
-used and as such we've learnt we can always figure out how to write a migration
+older migrations. This process was in place for 4 years without ever being
+used and as such we've learned we can always figure out how to write a migration
 differently to avoid downtime.
 
 When writing your migrations, also consider that databases might have stale data
@@ -35,10 +35,21 @@ For GitLab.com, please take into consideration that regular migrations (under `d
 are run before [Canary is deployed](https://gitlab.com/gitlab-com/gl-infra/readiness/-/tree/master/library/canary/#configuration-and-deployment),
 and [post-deployment migrations](post_deployment_migrations.md) (`db/post_migrate`) are run after the deployment to production has finished.
 
+## Create database migrations
+
+To create a migration you can use the following Rails generator:
+
+```shell
+bundle exec rails g migration migration_name_here
+```
+
+This generates the migration file in `db/migrate`.
+
 ## Schema Changes
 
 Changes to the schema should be committed to `db/structure.sql`. This
-file is automatically generated by Rails, so you normally should not
+file is automatically generated by Rails when you run
+`bundle exec rails db:migrate`, so you normally should not
 edit this file by hand. If your migration is adding a column to a
 table, that column is added at the bottom. Please do not reorder
 columns manually for existing tables as this causes confusion to