How about an annotated settings file?
pbx
DEFAULT_FROM_EMAIL with SERVER_EMAIL).
That got me thinking: How about annotating the default settings file to
describe all available settings? I'm talking about something along the
lines of Apache's default httpd.conf.
I also like the convention used by the bogofilter.cf where default
values are explicitly shown in the config file too.
(http://cvs.sourceforge.net/viewcvs.py/bogofilter/bogofilter/bogofilter.cf.example?view=markup).
I didn't file a ticket yet because this seems like something reasonable
people could disagree on.
So, reasonable people, what do you think?
Jacob Kaplan-Moss
> That got me thinking: How about annotating the default settings
> file to
> describe all available settings? I'm talking about something along the
> lines of Apache's default httpd.conf.
You mean something like http://www.djangoproject.com/documentation/
settings/#available-settings ?
Jacob
pbx
descriptions of each setting, including the defaults. See the
bogofilter link.
pb
ToddG
commented you can just about completely configure and run it just by
reading the conf file (well, for small setups at least).
Luke Plant
> That got me thinking: How about annotating the default settings file
> to describe all available settings? I'm talking about something along
> the lines of Apache's default httpd.conf.
<snip>
> So, reasonable people, what do you think?
One of the problems with an annotated conf file is what happens at
upgrade time, when new config options have been added to the system.
In the case of httpd.conf, it's not too bad for me because dconf
(Debian conf system) is great and asks me what to do (i.e. doesn't
overwrite my updated version etc, and even shows me the differences
between the two). But that obviously isn't the case for everyone, and
certainly isn't feasible at all for Django. This means that you'll
still have to go and read the docs for full information, and your fully
annotated version is no longer fully annotated. Even worse are the
cases where a setting is deprecated, or subtleties about its meaning
are changed, but you might go on blindly believing what you read in
your ageing settings.py
Luke
--
"Mistakes: It could be that the purpose of your life is only to serve
as a warning to others." (despair.com)
Luke Plant || L.Plant.98 (at) cantab.net || http://lukeplant.me.uk/
pbx
*only* the settings that differ from the defaults (very helpful when
asking someone else for troubleshooting advice).
pbx
> One of the problems with an annotated conf file is what happens at
> upgrade time, when new config options have been added to the system.
> In the case of httpd.conf, it's not too bad for me because dconf
> (Debian conf system) is great and asks me what to do (i.e. doesn't
> overwrite my updated version etc, and even shows me the differences
> between the two). But that obviously isn't the case for everyone, and
> certainly isn't feasible at all for Django. This means that you'll
> still have to go and read the docs for full information, and your fully
> annotated version is no longer fully annotated. Even worse are the
> cases where a setting is deprecated, or subtleties about its meaning
> are changed, but you might go on blindly believing what you read in
> your ageing settings.py
These are all good points, and are pretty much the objections I
imagined.
I think, though, that upgrades are pretty tricky territory regardless.
There are already comments in settings.py, some of which are surely
going to be made incorrect by a future upgrade. And settings.py isn't
the only place where things need a careful going-over when switching
versions. When I switched from the trunk to magic-removal a few days
ago, settings.py was the least of my worries.
I'm not weddded to this idea by any means, I just wanted to give it a
good airing while we're still here in pre-1.0 land.
pb
Adrian Holovaty
> That got me thinking: How about annotating the default settings file to
> describe all available settings? I'm talking about something along the
> lines of Apache's default httpd.conf.
Note that django/conf/global_settings.py holds the default values for
every setting, and it's annotated. Of course, you don't edit that
file, so the annotation is mainly for Django developers rather than
Django users. The default settings.py file that's generated for
"django-admin.py startproject" just contains the basic settings that
most people will probably want to change.
So the question is, do we give the generated settings.py file all the
possible settings, or does it continue to have just the settings that
are commonly changed? I really could go either way on this.
Whatever we do, I like the idea Paul mentioned that we could generate
an intelligent "diff" of the settings to find out which settings
aren't default. Very cool!
Adrian
--
Adrian Holovaty
holovaty.com | djangoproject.com | chicagocrime.org
Russell Keith-Magee
> So the question is, do we give the generated settings.py file all the
> possible settings, or does it continue to have just the settings that
> are commonly changed? I really could go either way on this.
Personally, I like the idea of settings.py generating all the possible
settings, but with all the 'not normally required' settings present
(with documentation), but commented out. e.g., the generated
settings.py file would contain sections like:
# E-mail address that error messages come from.
#SERVER_EMAIL = 'root@localhost'
This exposes all settings so that newcomers know what is available for
configuration, shows the default value for those settings,
demonstrates the expected format if the user does want to customize
that setting. The settings that are currently exposed through
settings.py remain uncommented, indicating that user input is probably
required before the application is started for the first time.
Russ Magee %-)
ToddG
approach...
Maniac
>So the question is, do we give the generated settings.py file all the
>possible settings, or does it continue to have just the settings that
>are commonly changed? I really could go either way on this.
>
>
It's good that current settings.py looks small. This adds to the feeling
of perceived simplicity of Django. It is important because settings.py
is one of the first things that new user sees.
Russell Keith-Magee
> It's good that current settings.py looks small. This adds to the feeling
> of perceived simplicity of Django. It is important because settings.py
> is one of the first things that new user sees.
How about putting all the essential configuration items at the top of
the generated settings.py, with an obvious 'border' that marks
'optional, but possibly useful configuration options below this line';
e.g.,
...
INSTALLED_APPS = (
)
########################################
# Optional, but possibly useful configuration items follow
########################################
# E-mail address that error messages come from.
#SERVER_EMAIL = 'root@localhost'
...
Russ Magee %-)
Maniac
>How about putting all the essential configuration items at the top of
>the generated settings.py, with an obvious 'border' that marks
>'optional, but possibly useful configuration options below this line';
>e.g.,
>
This looks reasonable to me... In fact I don't know if it's really
needed when it's documented already. I'm just against unordered
couple-o-dozens-kilobytes config :-)