#32217: Add warning about missing 'migrations' package to migration docs
-------------------------------------+-------------------------------------
Reporter: Tim McCurrach | Owner: Tim
Type: | McCurrach
Cleanup/optimization | Status: new
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 <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/071.12490beb2b3e77190ff0f83770cfedfb%40djangoproject.com.
