[Django] #30597: Improve documentation on reseting an app's migrations to zero
Django
-----------------------------------------+------------------------
Reporter: Keryn Knight | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-----------------------------------------+------------------------
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 [https://docs.djangoproject.com/en/2.2/ref
/django-admin/#migrate this page]. That's it.
It's not clear what ''unapplying'' migrations means, unless you're
familiar with it already - it's not described
[https://docs.djangoproject.com/en/2.2/topics/migrations/ on this page]
after searching for "unapply" or "undo" or "reset" or "restart", 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/30597>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: Keryn Knight | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Description changed by Keryn Knight:
Old description:
> 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 [https://docs.djangoproject.com/en/2.2/ref
> /django-admin/#migrate this page]. That's it.
>
> It's not clear what ''unapplying'' migrations means, unless you're
> familiar with it already - it's not described
> [https://docs.djangoproject.com/en/2.2/topics/migrations/ on this page]
> after searching for "unapply" or "undo" or "reset" or "restart", 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.
New description:
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 [https://docs.djangoproject.com/en/2.2/ref
/django-admin/#migrate this page]. That's it.
It's not clear what ''unapplying'' migrations means, unless you're
familiar with it already - it's not described
[https://docs.djangoproject.com/en/2.2/topics/migrations/ 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.
--
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:1>
Django
-------------------------------------+-------------------------------------
Reporter: Keryn Knight | Owner: nobody
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by felixxm):
* type: New feature => Cleanup/optimization
Comment:
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
[https://docs.djangoproject.com/en/2.2/topics/migrations/ "migrations
topics"].
[https://docs.djangoproject.com/en/2.2/topics/migrations/ "migrations
topics"] contains information that `migrate` is responsible for unapplying
migrations and also a link to the
[https://docs.djangoproject.com/en/2.2/ref/django-admin/#migrate "migrate
doc"] with `zero` option (added 6 years ago, see
162f7b938f6cff91b1e4d6086ddcc88cbb1a1cd6).
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:2>
Django
-------------------------------------+-------------------------------------
Reporter: Keryn Knight | Owner: nobody
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by 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''
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:3>
Django
--------------------------------------+------------------------------------
Reporter: Keryn Knight | Owner: nobody
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by felixxm):
* stage: Unreviewed => Accepted
Comment:
OK, agreed. We can evaluate PR with documentation improvement in this
area.
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:4>
Django
--------------------------------------+------------------------------------
Reporter: Keryn Knight | Owner: nobody
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by felixxm):
Keryn, I hope you are interested in submitting a patch.
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:5>
Django
--------------------------------------+------------------------------------
Reporter: Keryn Knight | Owner: nobody
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by tapaswenipathak):
Hi folks: Can I PR?
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:6>
Django
-------------------------------------+-------------------------------------
Reporter: Keryn Knight | Owner:
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by davidmgvaz):
* owner: nobody => davidmgvaz
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:7>
Django
-------------------------------------+-------------------------------------
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by David Vaz):
[https://github.com/django/django/pull/11821 PR on Github]
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:8>
Django
-------------------------------------+-------------------------------------
Reporter: Keryn Knight | Owner: David Vaz
Type: | Status: assigned
Cleanup/optimization |
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by felixxm):
* has_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:9>
Django
-------------------------------------+-------------------------------------
Reporter: Keryn Knight | Owner: David Vaz
Type: | Status: assigned
Cleanup/optimization |
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
Changes (by felixxm):
* needs_better_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:10>
Django
-------------------------------------+-------------------------------------
Reporter: Keryn Knight | Owner: David Vaz
Type: | Status: assigned
Cleanup/optimization |
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"5d40de08566cc7f0987ea414e06f37e6ed4e019a" 5d40de0]:
{{{
#!CommitTicketReference repository=""
revision="5d40de08566cc7f0987ea414e06f37e6ed4e019a"
[3.0.x] Refs #30597 -- Added a warning about dependent apps when
unapplying migrations.
Backport of abba563c8635a52e8b657dee7708202e1f69433c from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:11>
Django
-------------------------------------+-------------------------------------
Reporter: Keryn Knight | Owner: David Vaz
Type: | Status: assigned
Cleanup/optimization |
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"abba563c8635a52e8b657dee7708202e1f69433c" abba563c]:
{{{
#!CommitTicketReference repository=""
revision="abba563c8635a52e8b657dee7708202e1f69433c"
Refs #30597 -- Added a warning about dependent apps when unapplying
migrations.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:12>
Django
-------------------------------------+-------------------------------------
Reporter: Keryn Knight | Owner: David Vaz
Type: | Status: assigned
Cleanup/optimization |
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"1ac2f25ec091847a2db313210eb9743ed3b0dabf" 1ac2f25e]:
{{{
#!CommitTicketReference repository=""
revision="1ac2f25ec091847a2db313210eb9743ed3b0dabf"
[2.2.x] Refs #30597 -- Added a warning about dependent apps when
unapplying migrations.
Backport of abba563c8635a52e8b657dee7708202e1f69433c from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:13>
Django
-------------------------------------+-------------------------------------
Reporter: Keryn Knight | Owner: David Vaz
Type: | Status: assigned
Cleanup/optimization |
Severity: Normal | Resolution:
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by felixxm):
* needs_better_patch: 1 => 0
* stage: Accepted => Ready for checkin
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:14>
Django
-------------------------------------+-------------------------------------
Reporter: Keryn Knight | Owner: David Vaz
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Mariusz Felisiak <felisiak.mariusz@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"45554fd5c5c6a536db3ce70d78646d3dc398cf08" 45554fd5]:
{{{
#!CommitTicketReference repository=""
revision="45554fd5c5c6a536db3ce70d78646d3dc398cf08"
Fixed #30597 -- Clarified how to unapply migrations.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:15>
Django
-------------------------------------+-------------------------------------
Reporter: Keryn Knight | Owner: David Vaz
Type: | Status: closed
Cleanup/optimization |
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"0c655f1df2b167d7f24cf41910500850722b0c17" 0c655f1d]:
{{{
#!CommitTicketReference repository=""
revision="0c655f1df2b167d7f24cf41910500850722b0c17"
[3.0.x] Fixed #30597 -- Clarified how to unapply migrations.
Backport of 45554fd5c5c6a536db3ce70d78646d3dc398cf08 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:16>
Django
-------------------------------------+-------------------------------------
Reporter: Keryn Knight | Owner: David Vaz
Type: | Status: closed
Cleanup/optimization |
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"4116b369b191f1830bbe761fa7fb29bf1becc8ef" 4116b369]:
{{{
#!CommitTicketReference repository=""
revision="4116b369b191f1830bbe761fa7fb29bf1becc8ef"
[2.2.x] Fixed #30597 -- Clarified how to unapply migrations.
Backport of 45554fd5c5c6a536db3ce70d78646d3dc398cf08 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/30597#comment:17>