Document how to add a database migration

[delvh]

This was always a point of confusion for new contributors, so let's clarify it.
Especially important is the addition that updating migrations should be written to only be executed once.

[jolheiser]

Is this what actually happens? I was always under the impression that past migrations should be left alone. There's less chance that an intermediate migration is missed that would cause some odd potential bug.

[delvh]

Well… It's at least what I've observed with previous deletions, see for example #23605…
we can also decide to use another process, but we should decide this now.

[silverwind]

Hmm, tricky topic. I think leaving the original as-is may be safer than no-oping it. Treat it kind of like a git history that is never rewritten.

[delvh]

In theory, I agree.
However, as you saw in #23605, it sometimes needs to be done.
What about a paragraph such as

If you delete a column or table, do not adapt the original migration adding it and all migrations inbetween.
There is only one exception: If the original migration was broken and didn't work on some databases, you can convert the original migration and every change in between referencing the deleted content to a no-op.

?

[silverwind]

Yeah sounds good. General rule should be to not alter old migrations except in the rare case they are broken, in wich case it is warranted to fix it and "rewrite history".

[silverwind]

@delvh will you update with it?

[denyskon]

@delvh It would be nice if we could have at least some docs about migrations. Are you still interested in this PR? If so, could you update your branch and resolve the open review comments?

[denyskon]

Closing as no response unfortunately