Documentation for TEMPLATE_CONTEXT_PROCESSORS could use additional warning.

[cyclops]

The documentation for TEMPLATE_CONTEXT_PROCESSORS, at:

​https://docs.djangoproject.com/en/1.3/ref/settings/#template-context-processors

could use a warning about over-riding the variable in settings.py, maybe something like:

"Warning - if you set this variable to add your own context processor, it will over-ride the default settings listed above. You must manually add the defaults back into the variable, for them to be available."

Note that this issue has come up and been documented also on StackOverflow: ​http://stackoverflow.com/questions/2246725/django-template-context-processors

[Aymeric Augustin]

The situation is identical for all other settings that have a non-empty tuple as default value, notably MIDDLEWARE_CLASSES.

Without a good patch, I'm reluctant to accept this ticket because we can't list all possible errors and this one doesn't look too hard to diagnose.

[Julien Phalip]

This could be a useful clarification for beginners, but since it applies to all settings it should be a global note at the top of the page.

[Yaşar Arabacı]

Added neccessary warning.

[Aymeric Augustin]

Please don't mark your own patches as RFC — the rule is that patches must be reviewed by someone who isn't the author. For more information see the contributing guide in the docs.

Documentation patches are reviewed on a regular basis, so don't worry, your patch will get attention eventually.

[Bas Peschier]

Thanks for your contribution; I do have a couple of remarks on the patch:

1. The suggested text focuses on what people should do instead of WHY they should do it, which feels to me to be belittling the reader a bit.
2. It's not only beginners who should be cautious, everybody should.
3. I believe Django is commonly referred to with a capital D.

I would suggest to rewrite it to a more general style ("be careful with settings in settings.py, because ...") and focus on the fact settings.py overrides the default settings.

[Yaşar Arabacı]

Re-written warnings according to remarks.

[Yaşar Arabacı]

Replying to aaugustin:

Please don't mark your own patches as RFC — the rule is that patches must be reviewed by someone who isn't the author.

Sorry, I didn't know. I am new to contributing to django.

Replying to bpeschier:

Thanks for your contribution; I do have a couple of remarks on the patch:

Thanks for the remarks. I attached a new patch file.

[Christopher Medrela]

The beginning of the warning is:

Be careful with the settings in settings.py, because settings in settings.py override the default values. Overriding some settings may cause ...

Word 'settings' is repeated and repeated. I suggest changing it to something like this

Be careful when you override default values of settings, because it may cause ...

Next, there is

... may cause some core or commonly used functions of Django to stop functioning ...

I'm not sure 'functioning' is good word. I prefer simpler words, for example:

... may cause some core or commonly used functions of Django to stop working correctly ...

yasar11732, you wrote

When overriding default values, you are advised to make sure that none of the functions of Django that you need requires previous setting to work correctly.

Are there features of Django that cannot work correctly with non default values of some settings? I'm asking because I'm new contributor and i don't know everything about Django.

If the setting you are trying to change consists of more than one value (e.g a tuple), ...

I suggest

If the setting you want to change is tuple, list or dictonary, ...

because there are more words 'want' than 'try' in tutorial. I'm not sure if 'is tuple, list or directory' is more clear than 'consists of more than one value'.

[Yaşar Arabacı]

Sorry for late response, I was busy lately. How about latest patch? And about your question, some features need some TEMPLATE_CONTEXT_PROCESSORS to be loaded for example.

[Aymeric Augustin]

I'm sorry, but I still feel this doesn't match very well the tone of the docs. I'm uploading a new proposal.

[Yaşar Arabacı]

I have disowned ticket. Someone else might own it if needed.

[Claude Paroz]

Aymeric, I like your version.

[Tim Graham]

In [17566]:

Fixed #16758 - Added a warning regarding overriding default settings; thanks cyclops for the suggestion & Aymeric Augustin for the patch.

[Tim Graham]

In [17567]:

[1.3.X] Fixed #16758 - Added a warning regarding overriding default settings; thanks cyclops for the suggestion & Aymeric Augustin for the patch.

Backport of r17566 from trunk.