Improve documentation on reseting an app's migrations to zero.

[Keryn Knight]

This came on IRC a while back, because someone didn't know how to effectively undo everything they'd done.

The entire documentation that I can find is as follows:
python manage.py migrate --help says Use the name "zero" to unapply all migrations, and so does ​this page. That's it.

It's not clear what unapplying migrations means, unless you're familiar with it already - it's not described ​on this page after searching for "unapply" or "undo" or "reset" or "restart" or "zero", nor is it clarified in the help text for the command, and the process of resetting an app's state to start-from-scratch isn't mentioned at all in the migrations docs, except for this tiny affordance.

[Mariusz Felisiak]

Thanks for the report. I'm not sure how we could clarify what "unapplying" migrations means, it seems clear to me. Moreover my understanding is that it's not a common use case to unapply all migrations to "zero" state, so I don't think that it deserves a separate section in ​migrations topics.

​migrations topics contains information that migrate is responsible for unapplying migrations and also a link to the ​migrate doc with zero option (added 6 years ago, see 162f7b938f6cff91b1e4d6086ddcc88cbb1a1cd6).

[Keryn Knight]

Thanks for the report. I'm not sure how we could clarify what "unapplying" migrations means, it seems clear to me.

You're not the target audience though. Nor am I. All the synonyms I used in searching are ones I might expect new/inexperienced users to be looking for.

Moreover my understanding is that it's not a common use case to unapply all migrations to "zero" state, so I don't think that it deserves a separate section in migrations topics.

That it's uncommon is precisely why it should have documentation beyond the brief throwaway comment* the management command has. It's built in and supported! Every time someone has to do so for the first time, it's either under guidance from someone who knows better, or it's by trial and error. That should not be the case, because there is one way to do it, and one way only, and it's mostly that the concept isn't even discussed which leaves the user out in the cold.

It comes up relatively frequently on IRC that people get their migrations all in a muddle, and usually their answer is to just obliterate their database (sqlite usually) entirely (sometimes rightly, sometimes wrongly). But it's literally a solved problem from the framework's point of view: you can either reset to zero or your migrations and/or schema are so ruined that you need to start over or intervene manually.

* tbh, even South's documentation is better here, though it's almost as throwaway: Note that, if the system has already migrated past the specified migration, it will roll back to it instead. If you want to migrate all the way back, specify the special migration name zero

[Mariusz Felisiak]

OK, agreed. We can evaluate PR with documentation improvement in this area.

[Mariusz Felisiak]

Keryn, I hope you are interested in submitting a patch.

[Tapasweni Pathak]

Hi folks: Can I PR?

[David Vaz]

​PR on Github

[Mariusz Felisiak <felisiak.mariusz@…>]

In 5d40de0:

[3.0.x] Refs #30597 -- Added a warning about dependent apps when unapplying migrations.

Backport of abba563c8635a52e8b657dee7708202e1f69433c from master

[Mariusz Felisiak <felisiak.mariusz@…>]

In abba563c:

Refs #30597 -- Added a warning about dependent apps when unapplying migrations.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 1ac2f25e:

[2.2.x] Refs #30597 -- Added a warning about dependent apps when unapplying migrations.

Backport of abba563c8635a52e8b657dee7708202e1f69433c from master

[Mariusz Felisiak <felisiak.mariusz@…>]

In 45554fd5:

Fixed #30597 -- Clarified how to unapply migrations.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 0c655f1d:

[3.0.x] Fixed #30597 -- Clarified how to unapply migrations.

Backport of 45554fd5c5c6a536db3ce70d78646d3dc398cf08 from master

[Mariusz Felisiak <felisiak.mariusz@…>]

In 4116b369:

[2.2.x] Fixed #30597 -- Clarified how to unapply migrations.

Backport of 45554fd5c5c6a536db3ce70d78646d3dc398cf08 from master