Opened 3 years ago

Closed 3 years ago

Last modified 3 years ago

#32217 closed Cleanup/optimization (wontfix)

Add warning about missing 'migrations' package to migration docs

Reported by: Tim McCurrach Owned by: Tim McCurrach
Component: Documentation Version: 3.1
Severity: Normal Keywords:
Cc: Triage Stage: Unreviewed
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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.

Change History (5)

comment:1 by Tim McCurrach, 3 years ago

Owner: changed from nobody to Tim McCurrach

comment:2 by Mariusz Felisiak, 3 years ago

Resolution: invalid
Status: assignedclosed

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.

comment:3 by Tim McCurrach, 3 years ago

Resolution: invalid
Status: closednew

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

Last edited 3 years ago by Tim McCurrach (previous) (diff)

comment:4 by Carlton Gibson, 3 years ago

Resolution: wontfix
Status: newclosed

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.

in reply to:  4 comment:5 by Tim McCurrach, 3 years ago

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.

Note: See TracTickets for help on using tickets.
Back to Top