[Django] #28625: TIME_ZONE documentation is spectacularly unclear
Django
-----------------------------------------+------------------------
Reporter: Jon Ribbens | Owner: nobody
Type: Bug | Status: new
Component: Documentation | Version: 1.11
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 0 |
-----------------------------------------+------------------------
The documentation at https://docs.djangoproject.com/en/1.11/ref/settings
/#time-zone is spectacularly unclear that it's talking about the TIME_ZONE
sub-setting of the DATABASES setting, and not the top-level TIME_ZONE
setting.
--
Ticket URL: <https://code.djangoproject.com/ticket/28625>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: Jon Ribbens | Owner: nobody
Type: Bug | Status: new
Component: Documentation | Version: 1.11
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Aymeric Augustin):
* stage: Unreviewed => Accepted
Comment:
This is a spectacularly good point ;-) Would you like to submit a PR?
--
Ticket URL: <https://code.djangoproject.com/ticket/28625#comment:1>
Django
Reporter: Jon Ribbens | Owner: Jon Ribbens
Type: Bug | Status: assigned
Component: Documentation | Version: 1.11
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Jon Ribbens):
* status: new => assigned
* owner: nobody => Jon Ribbens
--
Ticket URL: <https://code.djangoproject.com/ticket/28625#comment:2>
Django
Reporter: Jon Ribbens | Owner: Jon Ribbens
Type: Bug | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Jon Ribbens):
* has_patch: 0 => 1
Comment:
[https://github.com/django/django/pull/9133 PR]
--
Ticket URL: <https://code.djangoproject.com/ticket/28625#comment:3>
Django
-------------------------------------+-------------------------------------
Reporter: Jon Ribbens | Owner: Jon
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.11
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Tim Graham):
* type: Bug => Cleanup/optimization
Comment:
Perhaps you could clarify how the confusion arose. I'm not immediately
convinced that a call out box is needed. My guess is that you used "find"
in a browser and encountered this as the first result. I think upon
reading the section, especially the second sentence, "The same values are
accepted as in the general TIME_ZONE setting." there's not much chance of
confusion.
Similar clashing names existing elsewhere, for example,
`CACHES['BACKEND']` and `TEMPLATES['BACKEND']`, so if this is really a
problem, it could be nice to find a more general solution.
--
Ticket URL: <https://code.djangoproject.com/ticket/28625#comment:4>
Django
-------------------------------------+-------------------------------------
Reporter: Jon Ribbens | Owner: Jon
Type: | Ribbens
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Jon Ribbens):
There's a general principle of course that if you are an expert in
something it can be very hard to know what will and will not be obvious to
non-experts. I couldn't comment on the probability of confusion in
general, all I can offer is the sure and certain fact that I was indeed
confused and it caused me a noticeable amount of wasted time trying to
work out how I was supposed to get times to be displayed in my chosen time
zone and investigating what I was supposed to do about TIME_ZONE having
been set by `django-admin startproject` in apparent contradiction to the
documentation which seemed to say that it must not be set if USE_TZ is set
(since I'm using PostgreSQL).
--
Ticket URL: <https://code.djangoproject.com/ticket/28625#comment:5>
Django
-------------------------------------+-------------------------------------
Reporter: Jon Ribbens | Owner: Jon
Type: | Ribbens
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham):
Why do you think "The same values are accepted as in the general TIME_ZONE
setting." didn't give a clue? Maybe it would be sufficient to add some
clarification to that sentence, e.g. This inner option of DATABASES
accepts the same values as the general TIME_ZONE setting."
Another option could be to prefix all the dictionary setting headers so it
appears as something like `DATABASES: TIME_ZONE`, but that would make the
table of contents less clean.
My goal is to find a solution that doesn't add too much extra verbosity
for someone reading the `DATABASES` setting docs from top to bottom
compared to someone skimming the docs.
--
Ticket URL: <https://code.djangoproject.com/ticket/28625#comment:6>
Django
-------------------------------------+-------------------------------------
Reporter: Jon Ribbens | Owner: Jon
Type: | Ribbens
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Jon Ribbens):
It didn't give a clue because I didn't know that there are two different
TIME_ZONE settings, so that sentence was meaningless to me; the phrase
"the general TIME_ZONE setting" tells you nothing if you don't know that
what you're looking for ''is'' the "general TIME_ZONE setting" and not
whatever unexplained thing this is that you're looking at.
The CACHES.BACKEND and TEMPLATES.BACKEND settings don't have the same
confusion as neither of them is a "general" setting and each of them
starts with the words "The cache backend to use" or "The template backend
to use" so there's no way you could be looking at one thinking it's the
other.
--
Ticket URL: <https://code.djangoproject.com/ticket/28625#comment:7>
Django
-------------------------------------+-------------------------------------
Reporter: Jon Ribbens | Owner: Jon
Type: | Ribbens
Component: Documentation | Version: 1.11
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Tim Graham <timograham@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"44f08422c872e32854216b2b30aab119ec3bb5d8" 44f0842]:
{{{
#!CommitTicketReference repository=""
revision="44f08422c872e32854216b2b30aab119ec3bb5d8"
Fixed #28625 -- Distinguished DATABASES['TIME_ZONE'] from
settings.TIME_ZONE.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/28625#comment:8>
Django
-------------------------------------+-------------------------------------
Reporter: Jon Ribbens | Owner: Jon
Type: | Ribbens
Cleanup/optimization | Status: closed
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"aff2df2427232807a88c2f408e7dc62b88f51cd0" aff2df2]:
{{{
#!CommitTicketReference repository=""
revision="aff2df2427232807a88c2f408e7dc62b88f51cd0"
[2.0.x] Fixed #28625 -- Distinguished DATABASES['TIME_ZONE'] from
settings.TIME_ZONE.
Backport of 44f08422c872e32854216b2b30aab119ec3bb5d8 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/28625#comment:9>