[Documentation] Add warnings about common migration problems about drift HOT 4 CLOSED

I agree with @dickermoshe about the linter, and moving to step-by-step migration is easy.

For now, my point is that when we see the onUpgrade function here, we tend to use the same way to write the migration code. So I suggest making it obvious that this way it discouraged.

Also it would be nice if we state in General tips something like 'Be careful when using the manual migration, don't let the code calls alterTable twice on the same table or  alterTable then addColumn

If you see that this will be taken care of and there is no need to let this issue open, feel free to close it :)

from drift.

I've updated the docs in f74c5fa to position the tools more prominently and to point out this footgun in particular.

from drift.

We're in middle of a complete docs refresh.
The new docs will do a better job of explaining how migrations should be done.

However we already warn how step-by-step migrations are a requirement to write a working migrations.

Drift makes is very easy to test and verify migrations.
It would be easier to build an automatic migration system than to build a linter that could figure out if the migrations are being done incorrectly.

Moving to step-by-step migrations is quite simple.

If you feel this is a reasonable position, close the issue. I won't close it myself, I don't like telling people their issues aren't important.

from drift.

A downside of step by step migrations is that users may still run into this problem with their existing migrations not covered by tests/step-by-step migrations.

I'll add a warning box to the main migration page strongly suggesting the use of these tools. With the rewrite we should probably just highlight the tools as the default way to do things and mention manual setups as a fallback.

from drift.