[Django] #32217: Add warning about missing 'migrations' package to migration docs

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

[Django] #32217: Add warning about missing 'migrations' package to migration docs

Django
#32217: Add warning about missing 'migrations' package to migration docs
------------------------------------------------+--------------------------
               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.

--
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 [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/django-updates/056.ae9850d33e1cf8549df244691415d2e2%40djangoproject.com.
Reply | Threaded
Open this post in threaded view
|

Re: [Django] #32217: Add warning about missing 'migrations' package to migration docs

Django
#32217: Add warning about missing 'migrations' package to migration docs
-------------------------------------+-------------------------------------
     Reporter:  Tim McCurrach        |                    Owner:  Tim
         Type:                       |  McCurrach
  Cleanup/optimization               |                   Status:  assigned
    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):

 * owner:  nobody => Tim McCurrach


--
Ticket URL: <https://code.djangoproject.com/ticket/32217#comment:1>
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 [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/django-updates/071.188b233c879407b8ce54d97373ea4077%40djangoproject.com.
Reply | Threaded
Open this post in threaded view
|

Re: [Django] #32217: Add warning about missing 'migrations' package to migration docs

Django
In reply to this post by Django
#32217: Add warning about missing 'migrations' package to migration docs
-------------------------------------+-------------------------------------
     Reporter:  Tim McCurrach        |                    Owner:  Tim
         Type:                       |  McCurrach
  Cleanup/optimization               |                   Status:  closed
    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 <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 [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/django-updates/071.a539de0ab93c0561f49f24526fa69dd3%40djangoproject.com.
Reply | Threaded
Open this post in threaded view
|

Re: [Django] #32217: Add warning about missing 'migrations' package to migration docs

Django
In reply to this post by Django
#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 [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/django-updates/071.12490beb2b3e77190ff0f83770cfedfb%40djangoproject.com.
Reply | Threaded
Open this post in threaded view
|

Re: [Django] #32217: Add warning about missing 'migrations' package to migration docs

Django
In reply to this post by Django
#32217: Add warning about missing 'migrations' package to migration docs
-------------------------------------+-------------------------------------
     Reporter:  Tim McCurrach        |                    Owner:  Tim
         Type:                       |  McCurrach
  Cleanup/optimization               |                   Status:  closed
    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 <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 [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/django-updates/071.c7ca158801d8ac578e2159785e84c9c4%40djangoproject.com.
Reply | Threaded
Open this post in threaded view
|

Re: [Django] #32217: Add warning about missing 'migrations' package to migration docs

Django
In reply to this post by Django
#32217: Add warning about missing 'migrations' package to migration docs
-------------------------------------+-------------------------------------
     Reporter:  Tim McCurrach        |                    Owner:  Tim
         Type:                       |  McCurrach
  Cleanup/optimization               |                   Status:  closed
    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
-------------------------------------+-------------------------------------

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>
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 [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/django-updates/071.e1a404c14c5b2c889c80e83b587cec75%40djangoproject.com.