Add docs about how to finalize BBM
What does this MR do and why?
Add docs about how finalizing BBM
This adds a specific section that describes what is involved in finalizing a batched background migration. This information is somewhat scattered around examples and other places right now and it didn't seem like we had any specific place to put it.
The main reason I wanted to add this doc to begin with was to highlight
that the gitlab_schema
must not change from queue to ensure. But I
couldn't find any place to put it so I made a new section and then I
also dumped all the other rules I know of in this section.
The gitlab_schema
rule documented here will become very important in
the next few months as we'll be changing hundreds of tables from
gitlab_main
to gitlab_main_cell
so we want to be extra clear about
this.
This is also in response to this issue we had before !139353 (merged) . It would be nice if this was detected by RSpec but then ultimately I'm not really sure what would be the right strategy for that. Because clearly we want to support running the same migration with different gitlab_schema if we are persisting this in the DB. I guess at least we could require that any ensure_
corresponds to some queue_
that was added in the past. But then again our implementation is very forgiving and just allows us to ignore when it doesn't find anything so I don't really get the reasoning behind that.
Also see !139876 (merged) for a related fix to our migration helpers.
Screenshots or screen recordings
Screenshots are required for UI changes, and strongly recommended for all other merge requests.
Before | After |
---|---|
How to set up and validate locally
Numbered steps to set up and validate the change are strongly suggested.
MR acceptance checklist
This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.
-
I have evaluated the MR acceptance checklist for this MR.