#16671: 5th tutorial on turning Polls into a reusable app
-------------------------------+------------------------------------
Reporter: stumbles | Owner: ben@…
Type: New feature | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+------------------------------------
Comment (by russellm):
Another good looking documentation addition. Some notes:
* The shoutout to djangopackages.com -- I agree this is the best resource
in this particular space at the moment -- but that's *at the moment*.
There have been others in the past, and as a project, we dont' have any
guarantees that djangopackages will be around next week. This may be a
case of something that we need to fix at a project level by formalizing
the relationship with djangopackages, rather than changing the text here.
* In crossover from my comments on #18715; The introduction of app-level
template directories seems more appropriate here, but it might still be
worth a shoutout in Tutorial 3 letting people know that this option exists
(even if you don't go into details)
* The "Why nested" note -- an example would help here. Show how a
template name like "base.html" would easily collide between apps.
* Regarding distutils vs distribute: This is one of those areas where I
think Django has a responsibility to be a community leader. The
[http://guide.python-distribute.org Hitchhikers guide to Python Packaging]
(which is itself worth a callout in the docs) recommends distribute; and
everything I've seen says that the features of distribute will ultimately
become part of distutils2; it seems to me that recommending distribute is
the right thing to do here. AFAIK, the only reason Django itself doesn't
use distribute is historical; setuptools had some pathological behavior
back in the day, and nobody has had enough of an itch to make the change.
Call this a +0 for distribute from me.
* The packaging says to create a README; it doesn't say create a LICENSE
file. We *must* say this. Code without a license is *useless*. Simliarly,
the setup.py file doesn't specify a license definition. By way of
communtiy guidance, we can say "Django, and many Django-compatible apps
are distributed under the BSD license; however, you're free to pick your
own license. However, be aware that your licensing choice will affect who
is able to use your code".
* The setup.py also doesn't mention any trove classifiers. It should. At
the very least, we should be able to say:
{{{
'Environment :: Web Environment',
'Framework :: Django',
'Intended Audience :: Developers',
'License :: OSI Approved :: BSD License',
'Operating System :: OS Independent',
'Programming Language :: Python',
'Programming Language :: Python :: 2.6',
'Programming Language :: Python :: 2.7',
'Topic :: Internet :: WWW/HTTP',
'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
}}}
* Again, I'm a little hesitant to link out to third-party blogs and
projects in the "more about" section. If we need to elaborate best
practices, I'd say we should distil Eric's blog post into a couple of
paragraphs of best practices; if we need to link to a list of packages,
djangopackages.com would seem a better candidate (with the caveat from
above).
--
Ticket URL: <https://code.djangoproject.com/ticket/16671#comment:22>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to django-updates@googlegroups.com.
To unsubscribe from this group, send email to
django-updates+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
