[Django] #32217: Add warning about missing 'migrations' package to migration docs
Django
------------------------------------------------+--------------------------
Reporter: Tim McCurrach | Owner: nobody
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: 3.1
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 1
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
------------------------------------------------+--------------------------
If you create an app with no migrations folder, then running
`makemigrations` won't make migrations for that app. This isn't really
mentioned in the migrations doc. There is a section dedicated to apps
where the database is already set up and migrations are missing, but
someone who has simply created an app manually might gloss over that
section. The only place I could actually find this written down is in a
comment in `db.migrations.questioner` (lines 26-33).
I have been bitten by this a few times, and only noticed my migrations
weren't added until further on down the line when I get a database error.
I think it would be helpful to have the above explicitly stated in the
docs.
--
Ticket URL: <https://code.djangoproject.com/ticket/32217>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: Tim McCurrach | Owner: Tim
Type: | McCurrach
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 3.1
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Tim McCurrach):
* owner: nobody => Tim McCurrach
--
Ticket URL: <https://code.djangoproject.com/ticket/32217#comment:1>
Django
Reporter: Tim McCurrach | Owner: Tim
Type: | McCurrach
Component: Documentation | Version: 3.1
Severity: Normal | Resolution: invalid
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Mariusz Felisiak):
* status: assigned => closed
* resolution: => invalid
Comment:
This behavior is already documented in the `makemigrations`
[https://docs.djangoproject.com/en/3.1/ref/django-admin/#makemigrations
docs]:
{{{
To add migrations to an app that doesn't have a migrations directory, run
makemigrations with the app's app_label.
}}}
and in the `MIGRATION_MODULES`
[https://docs.djangoproject.com/en/3.1/ref/settings/#std:setting-
MIGRATION_MODULES docs]:
{{{
If you provide the app_label argument, makemigrations will automatically
create the package if it doesn’t already exist.
When you supply None as a value for an app, Django will consider the app
as an app without migrations regardless of an existing migrations
submodule.
}}}
I think that's enough.
--
Ticket URL: <https://code.djangoproject.com/ticket/32217#comment:2>
Django
Reporter: Tim McCurrach | Owner: Tim
Type: | McCurrach
Component: Documentation | Version: 3.1
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Tim McCurrach):
* status: closed => new
* resolution: invalid =>
Comment:
Thank you very much for taking the time to look at this :)
In spite of the above quotes from the docs, I still think that this is not
clear enough in the documentation.
To clarify what I think needs highlighting:
- it is not that running "makemigrations app_name" will create a
migrations directory. That is clear enough, and not knowing it doesn't
have any real consequences since it is trivial to create a folder.
- What I don't think is particularly clear is that "''if you have not
created a migrations folder, running makemigrations by itself will do
absolutely nothing''". **Not knowing this piece of information can
completely stop the progress of your project - and so it is vital that it
is communicated clearly.**
The first quote above (from the django-admin docs page) does perhaps imply
that just running makemigrations by itself might not work if your app
doesn't already have a migrations folder, but it certainly doesn't make it
explicit.
I don't think the second quote (from the settings docs page) even implies
it. It reads as a nice extra that makemigrations will do for you. (I admit
that if you spent a moment to think that without a migrations folder,
there won't be any migtations, and that if adding the app_name means a
migrations folder will be created then perhaps without the app_name a
migrations folder won't be created, hence no migrations. But I really
think it could be made a lot more explicit than that.)
Further to the above (and perhaps more importantly), if I have a problem
with migrations, I'm unlikely to look at the django-admin docs page, or to
look up an obscure setting. This information really should be on the
migrations page. Even googling "django makemigrations" directs you towards
the migrations page. **Given the difficulty caused by not knowing this, it
should be impossible for someone to read the migrations page in the docs
and still not know it.**
Especially as it seems like such an easy trap to fall into.
Perhaps it's my reading of the docs is off, and if the feeling is still
that this is already stated clearly then I accept that. (But to my mind it
seems like it's a point that should be made clearer).
--
Ticket URL: <https://code.djangoproject.com/ticket/32217#comment:3>
Django
Reporter: Tim McCurrach | Owner: Tim
Type: | McCurrach
Component: Documentation | Version: 3.1
Severity: Normal | Resolution: wontfix
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Carlton Gibson):
* status: new => closed
* resolution: => wontfix
Comment:
Hi Tim. Thanks for the report.
I have to say I agree with Mariusz. The migrations topic links directly to
the command docs, which state the behaviour quite clearly.
It's stated that migrations live in the migrations directory and I don't
think labouring what happens if that's missing, or adding multiple links
to the same command docs from the same section would add clarity. Equally
I'm not sure that there's a better place for this than the
`makemigrations` command docs.
Docs can always be better, so if you which to suggest changes we're happy
to review.
--
Ticket URL: <https://code.djangoproject.com/ticket/32217#comment:4>
Django
Reporter: Tim McCurrach | Owner: Tim
Type: | McCurrach
Cleanup/optimization | Status: closed
Severity: Normal | Resolution: wontfix
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Tim McCurrach):
Fair enough. I'll concede this one haha.
Thanks both for reviewing it :)
Replying to [comment:4 Carlton Gibson]:
> Hi Tim. Thanks for the report.
>
> I have to say I agree with Mariusz. The migrations topic links directly
to the command docs, which state the behaviour quite clearly.
>
> It's stated that migrations live in the migrations directory and I don't
think labouring what happens if that's missing, or adding multiple links
to the same command docs from the same section would add clarity. Equally
I'm not sure that there's a better place for this than the
`makemigrations` command docs.
>
> Docs can always be better, so if you which to suggest changes we're
happy to review.
--
Ticket URL: <https://code.djangoproject.com/ticket/32217#comment:5>