Add latest changes from gitlab-org/gitlab@master

1 files changed, 9 insertions, 0 deletions

diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md
index f59c1fd8368..529b0802991 100644
--- a/doc/development/migration_style_guide.md
+++ b/doc/development/migration_style_guide.md
@@ -52,9 +52,18 @@ work it needs to perform and how long it takes to complete:
    of release manager through the [post-deploy migration pipeline](https://gitlab.com/gitlab-org/release/docs/-/blob/master/general/post_deploy_migration/readme.md#how-to-determine-if-a-post-deploy-migration-has-been-executed-on-gitlabcom).
    These migrations can be used for schema changes that aren't critical for the application to operate, or data migrations that take at most a few minutes.
    Common examples for schema changes that should run post-deploy include:
+
      - Clean-ups, like removing unused columns.
      - Adding non-critical indices on high-traffic tables.
      - Adding non-critical indices that take a long time to create.
+
+   These migrations should not be used for schema changes that are critical for the application to operate. Making such
+   schema changes in a post-deployment migration have caused issues in the past, for example [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/378582).
+   Changes that should always be a regular schema migration and not be executed in a post-deployment migration include:
+
+     - Creating a new table, example: `create_table`.
+     - Adding a new column to an existing table, example: `add_column`.
+
 1. [**Batched background migrations.**](database/batched_background_migrations.md) These aren't regular Rails migrations, but application code that is
    executed via Sidekiq jobs, although a post-deployment migration is used to schedule them. Use them only for data migrations that
    exceed the timing guidelines for post-deploy migrations. Batched background migrations should _not_ change the schema.