Merge branch 'bwill/document-bbm-code-deletion' into 'master'

Document the process for deleting BBM code

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/168847



Merged-by: Prabakaran Murugesan <pmurugesan@gitlab.com>
Approved-by: Jon Jenkins <jjenkins@gitlab.com>
Approved-by: Prabakaran Murugesan <pmurugesan@gitlab.com>
Reviewed-by: Brian Williams <bwilliams@gitlab.com>
Reviewed-by: Prabakaran Murugesan <pmurugesan@gitlab.com>
Co-authored-by: Brian Williams <bwilliams@gitlab.com>

doc/development/database/batched_background_migrations.md

@@ -292,11 +292,27 @@ the migration that was used to enqueue it. Pay careful attention to:
 When finalizing a batched background migration you also need to update the
 `finalized_by` in the corresponding `db/docs/batched_background_migrations`
 file. The value should be the timestamp/version of the migration you added to
-finalize it.
+finalize it. The [schema version of the RSpec tests](../testing_guide/testing_migrations_guide.md#testing-a-non-activerecordmigration-class)
+associated with the migration should also be set to this version to avoid having the tests fail due
+to future schema changes.
 See the below [Examples](#examples) for specific details on what the actual
 migration code should be.
+### Deleting batched background migration code
+
+Once a batched background migration has been finalized, the migration code in `lib/gitlab/background_migration/`
+and its associated tests can be deleted after the next required stop following the finalization.
+
+Here is an example scenario:
+
+- 17.2 and 17.5 are required stops.
+- In 17.0 the batched background migration is queued.
+- In 17.3 the migration may be finalized, provided that it's completed in GitLab.com.
+- In 17.6 the code related to the migration may be deleted.
+
+Batched background migration code is routinely deleted when migrations are squashed.
+
 ### Use job arguments
 `BatchedMigrationJob` provides the `job_arguments` helper method for job classes to define the job arguments they need.