Opened 2 months ago

Closed 7 weeks ago

Last modified 7 weeks ago

#28625 closed Cleanup/optimization (fixed)

DATABASES TIME_ZONE setting may be confused with TIME_ZONE

Reported by: Jon Ribbens Owned by: Jon Ribbens
Component: Documentation Version: 1.11
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

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.

Change History (9)

comment:1 Changed 2 months ago by Aymeric Augustin

Triage Stage: UnreviewedAccepted

This is a spectacularly good point ;-) Would you like to submit a PR?

comment:2 Changed 2 months ago by Jon Ribbens

Owner: changed from nobody to Jon Ribbens
Status: newassigned

comment:3 Changed 2 months ago by Jon Ribbens

Has patch: set

comment:4 Changed 8 weeks ago by Tim Graham

Summary: TIME_ZONE documentation is spectacularly unclearDATABASES TIME_ZONE setting may be confused with TIME_ZONE
Type: BugCleanup/optimization

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.

comment:5 Changed 8 weeks ago 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).

comment:6 Changed 8 weeks ago 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.

comment:7 Changed 8 weeks ago 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.

comment:8 Changed 7 weeks ago by Tim Graham <timograham@…>

Resolution: fixed
Status: assignedclosed

In 44f0842:

Fixed #28625 -- Distinguished DATABASESTIME_ZONE? from settings.TIME_ZONE.

comment:9 Changed 7 weeks ago by Tim Graham <timograham@…>

In aff2df2:

[2.0.x] Fixed #28625 -- Distinguished DATABASESTIME_ZONE? from settings.TIME_ZONE.

Backport of 44f08422c872e32854216b2b30aab119ec3bb5d8 from master

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