Add warning about missing 'migrations' package to migration docs

[Tim McCurrach]

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.

[Mariusz Felisiak]

This behavior is already documented in the 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 ​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.

[Tim McCurrach]

Replying to Mariusz Felisiak:

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).

[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.

[Tim McCurrach]

Fair enough. I'll concede this one haha.

Thanks both for reviewing it :)

Replying to 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.