Simplify the default project template

[Aymeric Augustin]

Hello,

I know I'm treading in contentious territory, but -- I figured I'd try anyway :)

We regularly hear complaints about the default settings file. I've noticed the following patterns:

1) Beginners

a) Frustration. They skim the comments, tweak the settings and it doesn't work as expected. The comments are fairly detailed, but they don't provide context like the docs.

b) Confusion. There's too much information at once. "What am I supposed to configure? Is STATICFILES_FINDERS important?"

2) Experienced users

a) Boredom. "Why do I have to make the same changes in every new project to enable the admin?"

b) Doubt. "Is using STATICFILES_DIRS the current best practice? It's in the default settings file."

Custom templates have improved the situation for advanced users, allowing us to focus on making the default project template as simple and straightforward as possible.

For this purpose, I've created a branch with the following changes:

1) Add links to the documentation. Remove comments. Documentation goes in the docs, not in comments.

2) Keep only the most relevant settings in the default settings.py.

3) Various improvements along the way.

Compare view: https://github.com/aaugustin/django/compare/simplify-project-template

Right now the branch shows that the default settings file can be trimmed to 80 lines. I'm reasonably satisfied with the project and app template. I still have to synchronize the docs with the changes, especially the tutorial.

Questions:

- In general, do you think this is a good idea? Or am I misguided?

- In detail, are there commits in the branch that seem wrong with regard to the current best practices? I don't claim to know them all.

Thanks,

-- 

Aymeric.

PS: I've purposefully avoided the concept of BASE_DIR because I feel we can't reach a consensus on this right now.

[Jacob Kaplan-Moss]

On Mon, Jan 28, 2013 at 3:54 PM, Aymeric Augustin
<aymeric....@polytechnique.org> wrote:
> We regularly hear complaints about the default settings file. I've noticed
> the following patterns:
>
> 1) Beginners
> a) Frustration. They skim the comments, tweak the settings and it doesn't
> work as expected. The comments are fairly detailed, but they don't provide
> context like the docs.
> b) Confusion. There's too much information at once. "What am I supposed to
> configure? Is STATICFILES_FINDERS important?"
>
> 2) Experienced users
> a) Boredom. "Why do I have to make the same changes in every new project to
> enable the admin?"
> b) Doubt. "Is using STATICFILES_DIRS the current best practice? It's in the
> default settings file."

I can confirm both of these patterns, especially 1a -- settings.py
tends to be really overwhelming when I teach Django to new users. The
first time we make a new app in my classes it can take like 5-10
minutes for everyone to figure out how to add it to INSTALLED_APPS.

> - In general, do you think this is a good idea? Or am I misguided?

I think it's a great idea -- +1.

> - In detail, are there commits in the branch that seem wrong with regard to
> the current best practices? I don't claim to know them all.

I'll bet if *I* wrote this patch I'd do it slightly differently, but I
don't see anything that's not more a matter of taste than anything
technical. I don't want to contribute to any bikeshedding; this is
good enough for me.

Jacob

[Ryan D Hiebert]

Since the admin is turned on by default, should there be a admin.py template file in the app template as well?

Ryan

[ptone]

Aymeric,

I think this is a great start.

I particularly like inserting the links to docs in the form of docs.djangoproject.com/en/{{ docs_version }}/*

I actually think these sorts of links could be added to admin.py and views.py as well.

And at least one other could be made more specific (the "see documentation" note for DATABASES).

This combined with Tim's recent doc improvements will result in some solid improvements for settings.

-Preston

[Aymeric Augustin]

Hello,

I took into account the feedback received here and on IRC (thanks everyone!) and I now have a branch ready for review:

https://github.com/aaugustin/django/compare/simplify-project-template

The commit messages give some hints about the reasoning behind each change. I'll be glad to provide more detailed explanations if necessary.

Like Jacob said, everyone here would certainly do this a bit differently. Let's avoid bikeshedding — if you can't resist, tell me in private — and look for problems such as:

- I got the priorities wrong: forgot something important / included something useless,

- I missed some best practices,

- I did something that's likely to trip up beginners,

- etc.

I plan to commit this next week. Let me know if you'd like more time to review.

Thank you,

-- 

Aymeric.

[Josh Cartmell]

Long time lurker here. Anyways, one thing that I think might trip up
beginners is this line:
# Quick-start development settings - unsuitable for production

For a beginner that could be a very daunting statement that could
leave them wondering:
Why is this unsuitable for production and what is suitable for
production? Is it inefficient or insecure or both?

I think a little more explanation regarding it's unsuitability would
make it a lot less scary. In line with what you have done here it
might make sense to add a new section to the docs describing how to
make the default settings production ready and then link to it after
that statement.

On Jan 29, 1:01 pm, Aymeric Augustin

[Aymeric Augustin]

Le 31 janv. 2013 à 17:46, Josh Cartmell <joshc...@gmail.com> a écrit :

> I think a little more explanation regarding it's unsuitability would
> make it a lot less scary. In line with what you have done here it
> might make sense to add a new section to the docs describing how to
> make the default settings production ready and then link to it after
> that statement.

Indeed, that's the plan — we just need someone to write that document :)

https://code.djangoproject.com/ticket/19697

--
Aymeric.