mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-08-04 02:48:35 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Fixed many more ReST indentation errors, somehow accidentally missed from [16955]

Browse source 
git-svn-id: http://code.djangoproject.com/svn/django/trunk@16983 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Luke Plant 2011-10-14 00:12:01 +00:00
parent 5109ac3709
commit d1e5c55258
129 changed files with 5708 additions and 5740 deletions
Download patch file Download diff file Expand all files Collapse all files

150
docs/internals/contributing/bugs-and-features.txt
View file

@ -30,23 +30,23 @@ amount of overhead involved in working with any bug tracking system so your
help in keeping our ticket tracker as useful as possible is appreciated. In
particular:
* **Do** read the :doc:`FAQ </faq/index>` to see if your issue might
be a well-known question.
* **Do** read the :doc:`FAQ </faq/index>` to see if your issue might
be a well-known question.
* **Do** ask on `django-users`_ or `#django`_ *first* if you're not sure if
what you're seeing is a bug.
* **Do** ask on `django-users`_ or `#django`_ *first* if you're not sure if
what you're seeing is a bug.
* **Do** write complete, reproducible, specific bug reports. You must
include a clear, concise description of the problem, and a set of
instructions for replicating it. Add as much debug information as you can:
code snippets, test cases, exception backtraces, screenshots, etc. A nice
small test case is the best way to report a bug, as it gives us an easy
way to confirm the bug quickly.
* **Do** write complete, reproducible, specific bug reports. You must
include a clear, concise description of the problem, and a set of
instructions for replicating it. Add as much debug information as you can:
code snippets, test cases, exception backtraces, screenshots, etc. A nice
small test case is the best way to report a bug, as it gives us an easy
way to confirm the bug quickly.
* **Don't** post to `django-developers`_ just to announce that you have
filed a bug report. All the tickets are mailed to another list,
`django-updates`_, which is tracked by developers and interested
community members; we see them as they are filed.
* **Don't** post to `django-developers`_ just to announce that you have
filed a bug report. All the tickets are mailed to another list,
`django-updates`_, which is tracked by developers and interested
community members; we see them as they are filed.
To understand the lifecycle of your ticket once you have created it, refer to
:doc:`triaging-tickets`.
@ -67,27 +67,27 @@ Reporting security issues
In the event of a confirmed vulnerability in Django itself, we will take the
following actions:
* Acknowledge to the reporter that we've received the report and that a
fix is forthcoming. We'll give a rough timeline and ask the reporter
to keep the issue confidential until we announce it.
* Acknowledge to the reporter that we've received the report and that a
fix is forthcoming. We'll give a rough timeline and ask the reporter
to keep the issue confidential until we announce it.
* Focus on developing a fix as quickly as possible and produce patches
against the current and two previous releases.
* Focus on developing a fix as quickly as possible and produce patches
against the current and two previous releases.
* Determine a go-public date for announcing the vulnerability and the fix.
To try to mitigate a possible "arms race" between those applying the
patch and those trying to exploit the hole, we will not announce
security problems immediately.
* Determine a go-public date for announcing the vulnerability and the fix.
To try to mitigate a possible "arms race" between those applying the
patch and those trying to exploit the hole, we will not announce
security problems immediately.
* Pre-notify third-party distributors of Django ("vendors"). We will send
these vendor notifications through private email which will include
documentation of the vulnerability, links to the relevant patch(es), and
a request to keep the vulnerability confidential until the official
go-public date.
* Pre-notify third-party distributors of Django ("vendors"). We will send
these vendor notifications through private email which will include
documentation of the vulnerability, links to the relevant patch(es), and
a request to keep the vulnerability confidential until the official
go-public date.
* Publicly announce the vulnerability and the fix on the pre-determined
go-public date. This will probably mean a new release of Django, but
in some cases it may simply be patches against current releases.
* Publicly announce the vulnerability and the fix on the pre-determined
go-public date. This will probably mean a new release of Django, but
in some cases it may simply be patches against current releases.
Reporting user interface bugs and features
------------------------------------------
@ -95,25 +95,25 @@ Reporting user interface bugs and features
If your bug or feature request touches on anything visual in nature, there
are a few additional guidelines to follow:
* Include screenshots in your ticket which are the visual equivalent of a
minimal testcase. Show off the issue, not the crazy customizations
you've made to your browser.
* If the issue is difficult to show off using a still image, consider
capturing a *brief* screencast. If your software permits it, capture only
the relevant area of the screen.
* If you're offering a patch which changes the look or behavior of Django's
UI, you **must** attach before *and* after screenshots/screencasts.
Tickets lacking these are difficult for triagers and core developers to
assess quickly.
* Include screenshots in your ticket which are the visual equivalent of a
minimal testcase. Show off the issue, not the crazy customizations
you've made to your browser.
* Screenshots don't absolve you of other good reporting practices. Make sure
to include URLs, code snippets, and step-by-step instructions on how to
reproduce the behavior visible in the screenshots.
* If the issue is difficult to show off using a still image, consider
capturing a *brief* screencast. If your software permits it, capture only
the relevant area of the screen.
* Make sure to set the UI/UX flag on the ticket so interested parties can
find your ticket.
* If you're offering a patch which changes the look or behavior of Django's
UI, you **must** attach before *and* after screenshots/screencasts.
Tickets lacking these are difficult for triagers and core developers to
assess quickly.
* Screenshots don't absolve you of other good reporting practices. Make sure
to include URLs, code snippets, and step-by-step instructions on how to
reproduce the behavior visible in the screenshots.
* Make sure to set the UI/UX flag on the ticket so interested parties can
find your ticket.
Requesting features
-------------------
@ -121,27 +121,27 @@ Requesting features
We're always trying to make Django better, and your feature requests are a key
part of that. Here are some tips on how to make a request most effectively:
* Make sure the feature actually requires changes in Django's core. If your
idea can be developed as an independent application or module — for
instance, you want to support another database engine — we'll probably
suggest that you to develop it independently. Then, if your project
gathers sufficient community support, we may consider it for inclusion in
Django.
* Make sure the feature actually requires changes in Django's core. If your
idea can be developed as an independent application or module — for
instance, you want to support another database engine — we'll probably
suggest that you to develop it independently. Then, if your project
gathers sufficient community support, we may consider it for inclusion in
Django.
* First request the feature on the `django-developers`_ list, not in the
ticket tracker. It'll get read more closely if it's on the mailing list.
This is even more important for large-scale feature requests. We like to
discuss any big changes to Django's core on the mailing list before
actually working on them.
* First request the feature on the `django-developers`_ list, not in the
ticket tracker. It'll get read more closely if it's on the mailing list.
This is even more important for large-scale feature requests. We like to
discuss any big changes to Django's core on the mailing list before
actually working on them.
* Describe clearly and concisely what the missing feature is and how you'd
like to see it implemented. Include example code (non-functional is OK)
if possible.
* Describe clearly and concisely what the missing feature is and how you'd
like to see it implemented. Include example code (non-functional is OK)
if possible.
* Explain *why* you'd like the feature. In some cases this is obvious, but
since Django is designed to help real developers get real work done,
you'll need to explain it, if it isn't obvious why the feature would be
useful.
* Explain *why* you'd like the feature. In some cases this is obvious, but
since Django is designed to help real developers get real work done,
you'll need to explain it, if it isn't obvious why the feature would be
useful.
If core developers agree on the feature, then it's appropriate to create a
ticket. Include a link the discussion on `django-developers`_ in the ticket
@ -165,14 +165,14 @@ have informal votes on `django-developers`_ about a feature. In these votes we
follow the voting style invented by Apache and used on Python itself, where
votes are given as +1, +0, -0, or -1. Roughly translated, these votes mean:
* +1: "I love the idea and I'm strongly committed to it."
* +1: "I love the idea and I'm strongly committed to it."
* +0: "Sounds OK to me."
* +0: "Sounds OK to me."
* -0: "I'm not thrilled, but I won't stand in the way."
* -0: "I'm not thrilled, but I won't stand in the way."
* -1: "I strongly disagree and would be very unhappy to see the idea turn
into reality."
* -1: "I strongly disagree and would be very unhappy to see the idea turn
into reality."
Although these votes on `django-developers`_ are informal, they'll be taken very
seriously. After a suitable voting period, if an obvious consensus arises we'll
@ -186,12 +186,12 @@ Any :doc:`core committer</internals/committers>` may call for a formal vote
using the same voting mechanism above. A proposition will be considered carried
by the core team if:
* There are three "+1" votes from members of the core team.
* There are three "+1" votes from members of the core team.
* There is no "-1" vote from any member of the core team.
* There is no "-1" vote from any member of the core team.
* The :ref:`BDFLs<django-bdfls>` haven't stepped in and executed their
positive or negative veto.
* The :ref:`BDFLs<django-bdfls>` haven't stepped in and executed their
positive or negative veto.
When calling for a vote, the caller should specify a deadline by which
votes must be received. One week is generally suggested as the minimum

124
docs/internals/contributing/committing-code.txt
View file

@ -38,58 +38,58 @@ Committing guidelines
Please follow these guidelines when committing code to Django's Subversion
repository:
* For any medium-to-big changes, where "medium-to-big" is according to
your judgment, please bring things up on the `django-developers`_
mailing list before making the change.
* For any medium-to-big changes, where "medium-to-big" is according to
your judgment, please bring things up on the `django-developers`_
mailing list before making the change.
If you bring something up on `django-developers`_ and nobody responds,
please don't take that to mean your idea is great and should be
implemented immediately because nobody contested it. Django's lead
developers don't have a lot of time to read mailing-list discussions
immediately, so you may have to wait a couple of days before getting a
response.
If you bring something up on `django-developers`_ and nobody responds,
please don't take that to mean your idea is great and should be
implemented immediately because nobody contested it. Django's lead
developers don't have a lot of time to read mailing-list discussions
immediately, so you may have to wait a couple of days before getting a
response.
* Write detailed commit messages in the past tense, not present tense.
* Write detailed commit messages in the past tense, not present tense.
* Good: "Fixed Unicode bug in RSS API."
* Bad: "Fixes Unicode bug in RSS API."
* Bad: "Fixing Unicode bug in RSS API."
* Good: "Fixed Unicode bug in RSS API."
* Bad: "Fixes Unicode bug in RSS API."
* Bad: "Fixing Unicode bug in RSS API."
* For commits to a branch, prefix the commit message with the branch name.
For example: "magic-removal: Added support for mind reading."
* For commits to a branch, prefix the commit message with the branch name.
For example: "magic-removal: Added support for mind reading."
* Limit commits to the most granular change that makes sense. This means,
use frequent small commits rather than infrequent large commits. For
example, if implementing feature X requires a small change to library Y,
first commit the change to library Y, then commit feature X in a
separate commit. This goes a *long way* in helping all core Django
developers follow your changes.
* Limit commits to the most granular change that makes sense. This means,
use frequent small commits rather than infrequent large commits. For
example, if implementing feature X requires a small change to library Y,
first commit the change to library Y, then commit feature X in a
separate commit. This goes a *long way* in helping all core Django
developers follow your changes.
* Separate bug fixes from feature changes.
* Separate bug fixes from feature changes.
Bug fixes need to be added to the current bugfix branch as well as the
current trunk.
Bug fixes need to be added to the current bugfix branch as well as the
current trunk.
* If your commit closes a ticket in the Django `ticket tracker`_, begin
your commit message with the text "Fixed #abc", where "abc" is the
number of the ticket your commit fixes. Example: "Fixed #123 -- Added
support for foo". We've rigged Subversion and Trac so that any commit
message in that format will automatically close the referenced ticket
and post a comment to it with the full commit message.
* If your commit closes a ticket in the Django `ticket tracker`_, begin
your commit message with the text "Fixed #abc", where "abc" is the
number of the ticket your commit fixes. Example: "Fixed #123 -- Added
support for foo". We've rigged Subversion and Trac so that any commit
message in that format will automatically close the referenced ticket
and post a comment to it with the full commit message.
If your commit closes a ticket and is in a branch, use the branch name
first, then the "Fixed #abc." For example:
"magic-removal: Fixed #123 -- Added whizbang feature."
If your commit closes a ticket and is in a branch, use the branch name
first, then the "Fixed #abc." For example:
"magic-removal: Fixed #123 -- Added whizbang feature."
For the curious: we're using a `Trac post-commit hook`_ for this.
For the curious: we're using a `Trac post-commit hook`_ for this.
.. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook
.. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook
* If your commit references a ticket in the Django `ticket tracker`_ but
does *not* close the ticket, include the phrase "Refs #abc", where "abc"
is the number of the ticket your commit references. We've rigged
Subversion and Trac so that any commit message in that format will
automatically post a comment to the appropriate ticket.
* If your commit references a ticket in the Django `ticket tracker`_ but
does *not* close the ticket, include the phrase "Refs #abc", where "abc"
is the number of the ticket your commit references. We've rigged
Subversion and Trac so that any commit message in that format will
automatically post a comment to the appropriate ticket.
Reverting commits
-----------------
@ -97,35 +97,35 @@ Reverting commits
Nobody's perfect; mistakes will be committed. When a mistaken commit is
discovered, please follow these guidelines:
* Try very hard to ensure that mistakes don't happen. Just because we
have a reversion policy doesn't relax your responsibility to aim for
the highest quality possible. Really: double-check your work before
you commit it in the first place!
* Try very hard to ensure that mistakes don't happen. Just because we
have a reversion policy doesn't relax your responsibility to aim for
the highest quality possible. Really: double-check your work before
you commit it in the first place!
* If possible, have the original author revert his/her own commit.
* If possible, have the original author revert his/her own commit.
* Don't revert another author's changes without permission from the
original author.
* Don't revert another author's changes without permission from the
original author.
* If the original author can't be reached (within a reasonable amount
of time -- a day or so) and the problem is severe -- crashing bug,
major test failures, etc -- then ask for objections on the
`django-developers`_ mailing list then revert if there are none.
* If the original author can't be reached (within a reasonable amount
of time -- a day or so) and the problem is severe -- crashing bug,
major test failures, etc -- then ask for objections on the
`django-developers`_ mailing list then revert if there are none.
* If the problem is small (a feature commit after feature freeze,
say), wait it out.
* If the problem is small (a feature commit after feature freeze,
say), wait it out.
* If there's a disagreement between the committer and the
reverter-to-be then try to work it out on the `django-developers`_
mailing list. If an agreement can't be reached then it should
be put to a vote.
* If there's a disagreement between the committer and the
reverter-to-be then try to work it out on the `django-developers`_
mailing list. If an agreement can't be reached then it should
be put to a vote.
* If the commit introduced a confirmed, disclosed security
vulnerability then the commit may be reverted immediately without
permission from anyone.
* If the commit introduced a confirmed, disclosed security
vulnerability then the commit may be reverted immediately without
permission from anyone.
* The release branch maintainer may back out commits to the release
branch without permission if the commit breaks the release branch.
* The release branch maintainer may back out commits to the release
branch without permission if the commit breaks the release branch.
.. _django-developers: http://groups.google.com/group/django-developers
.. _ticket tracker: http://code.djangoproject.com/newticket

48
docs/internals/contributing/index.txt
View file

@ -6,43 +6,43 @@ Django is a community that lives on its volunteers. As it keeps growing, we
always need more people to help others. As soon as you learn Django, you can
contribute in many ways:
* Join the `django-users`_ mailing list and answer questions. This
mailing list has a huge audience, and we really want to maintain a
friendly and helpful atmosphere. If you're new to the Django community,
you should read the `posting guidelines`_.
* Join the `django-users`_ mailing list and answer questions. This
mailing list has a huge audience, and we really want to maintain a
friendly and helpful atmosphere. If you're new to the Django community,
you should read the `posting guidelines`_.
* Join the `#django IRC channel`_ on Freenode and answer questions. By
explaining Django to other users, you're going to learn a lot about the
framework yourself.
* Join the `#django IRC channel`_ on Freenode and answer questions. By
explaining Django to other users, you're going to learn a lot about the
framework yourself.
* Blog about Django. We syndicate all the Django blogs we know about on
the `community page`_; if you'd like to see your blog on that page you
can `register it here`_.
* Blog about Django. We syndicate all the Django blogs we know about on
the `community page`_; if you'd like to see your blog on that page you
can `register it here`_.
* Contribute to open-source Django projects, write some documentation, or
release your own code as an open-source pluggable application. The
ecosystem of pluggable applications is a big strength of Django, help us
build it!
* Contribute to open-source Django projects, write some documentation, or
release your own code as an open-source pluggable application. The
ecosystem of pluggable applications is a big strength of Django, help us
build it!
If you think working *with* Django is fun, wait until you start working *on*
it. We're passionate about helping Django users make the jump to contributing
members of the community, so there are several ways you can help Django's
development:
* :doc:`Report bugs <bugs-and-features>` in our `ticket tracker`_.
* :doc:`Report bugs <bugs-and-features>` in our `ticket tracker`_.
* Join the `django-developers`_ mailing list and share your ideas for how
to improve Django. We're always open to suggestions.
* Join the `django-developers`_ mailing list and share your ideas for how
to improve Django. We're always open to suggestions.
* :doc:`Submit patches <writing-code/submitting-patches>` for new and/or
fixed behavior. If you're looking for an easy way to start contributing
to Django have a look at the `easy pickings`_ tickets.
* :doc:`Submit patches <writing-code/submitting-patches>` for new and/or
fixed behavior. If you're looking for an easy way to start contributing
to Django have a look at the `easy pickings`_ tickets.
* :doc:`Improve the documentation <writing-documentation>` or
:doc:`write unit tests <writing-code/unit-tests>`.
* :doc:`Improve the documentation <writing-documentation>` or
:doc:`write unit tests <writing-code/unit-tests>`.
* :doc:`Triage tickets and review patches <triaging-tickets>` created by
other users.
* :doc:`Triage tickets and review patches <triaging-tickets>` created by
other users.
Really, **ANYONE** can do something to help make Django better and greater!

44
docs/internals/contributing/translations.txt
View file

@ -19,31 +19,31 @@ go to the `translation team`_ page for that language. If you would like to help
out with translating or add a language that isn't yet translated, here's what to
do:
* Join the `Django i18n mailing list`_ and introduce yourself.
* Join the `Django i18n mailing list`_ and introduce yourself.
* Make sure you read the notes about :ref:`specialties-of-django-i18n`.
* Make sure you read the notes about :ref:`specialties-of-django-i18n`.
* Signup at `Transifex`_ and visit the `Django project page`_.
* Signup at `Transifex`_ and visit the `Django project page`_.
* On the `translation teams`_ page, choose the language team you want
to work with, **or** -- in case the language team doesn't exist yet --
request a new team by clicking on the "Request a new team" button
and select the appropriate language.
* On the `translation teams`_ page, choose the language team you want
to work with, **or** -- in case the language team doesn't exist yet --
request a new team by clicking on the "Request a new team" button
and select the appropriate language.
* Then, click the "Join this Team" button to become a member of this team.
Every team has at least one coordinator who is responsible to review
your membership request. You can of course also contact the team
coordinator to clarify procedural problems and handle the actual
translation process.
* Then, click the "Join this Team" button to become a member of this team.
Every team has at least one coordinator who is responsible to review
your membership request. You can of course also contact the team
coordinator to clarify procedural problems and handle the actual
translation process.
* Once you are a member of a team choose the translation resource you
want to update on the team page. For example the "core" resource refers
to the translation catalogue that contains all non-contrib translations.
Each of the contrib apps also have a resource (prefixed with "contrib").
* Once you are a member of a team choose the translation resource you
want to update on the team page. For example the "core" resource refers
to the translation catalogue that contains all non-contrib translations.
Each of the contrib apps also have a resource (prefixed with "contrib").
.. note::
For more information about how to use Transifex, read the
`Transifex User Guide`_.
.. note::
For more information about how to use Transifex, read the
`Transifex User Guide`_.
Localization
------------
@ -55,10 +55,10 @@ the date, time and numbers formatting particularities of your locale. See
The format files aren't managed by the use of Transifex. To change them, you
must :doc:`create a patch<writing-code/submitting-patches>` against the Django source tree, as for any code change:
* Create a diff against the current Subversion trunk.
* Create a diff against the current Subversion trunk.
* Open a ticket in Django's ticket system, set its ``Component`` field to
``Translations``, and attach the patch to it.
* Open a ticket in Django's ticket system, set its ``Component`` field to
``Translations``, and attach the patch to it.
.. _Transifex: http://www.transifex.net/
.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/

228
docs/internals/contributing/triaging-tickets.txt
View file

@ -57,16 +57,16 @@ Since a picture is worth a thousand words, let's start there:
We've got two roles in this diagram:
* :doc:`Committers</internals/committers>` (also called core developers):
people with commit access who are responsible for making the big
decisions, writing large portions of the code and integrating the
contributions of the community.
* :doc:`Committers</internals/committers>` (also called core developers):
people with commit access who are responsible for making the big
decisions, writing large portions of the code and integrating the
contributions of the community.
* Ticket triagers: anyone in the Django community who chooses to
become involved in Django's development process. Our Trac installation
is intentionally left open to the public, and anyone can triage tickets.
Django is a community project, and we encourage :ref:`triage by the
community<how-can-i-help-with-triaging>`.
* Ticket triagers: anyone in the Django community who chooses to
become involved in Django's development process. Our Trac installation
is intentionally left open to the public, and anyone can triage tickets.
Django is a community project, and we encourage :ref:`triage by the
community<how-can-i-help-with-triaging>`.
By way of example, here we see the lifecycle of an average ticket:
@ -185,36 +185,40 @@ Other triage attributes
A number of flags, appearing as checkboxes in Trac, can be set on a ticket:
* Has patch
This means the ticket has an associated
:doc:`patch<writing-code/submitting-patches>`. These will be reviewed
to see if the patch is "good".
* Needs documentation:
This flag is used for tickets with patches that need associated
documentation. Complete documentation of features is a prerequisite
before we can check them into the codebase.
* Needs tests
This flags the patch as needing associated unit tests. Again, this
is a required part of a valid patch.
* Patch needs improvement
This flag means that although the ticket *has* a patch, it's not quite
ready for checkin. This could mean the patch no longer applies
cleanly, there is a flaw in the implementation, or that the code
doesn't meet our standards.
* Easy pickings
Tickets that would require small, easy, patches.
* Has patch
This means the ticket has an associated
:doc:`patch<writing-code/submitting-patches>`. These will be reviewed
to see if the patch is "good".
* Needs documentation:
This flag is used for tickets with patches that need associated
documentation. Complete documentation of features is a prerequisite
before we can check them into the codebase.
* Needs tests
This flags the patch as needing associated unit tests. Again, this
is a required part of a valid patch.
* Patch needs improvement
This flag means that although the ticket *has* a patch, it's not quite
ready for checkin. This could mean the patch no longer applies
cleanly, there is a flaw in the implementation, or that the code
doesn't meet our standards.
* Easy pickings
Tickets that would require small, easy, patches.
Tickets should be categorized by *type* between:
* New Feature
For adding something new.
* New Feature
For adding something new.
* Bug
For when an existing thing is broken or not behaving as expected.
* Bug
For when an existing thing is broken or not behaving as expected.
* Cleanup/optimization
For when nothing is broken but something could be made cleaner,
better, faster, stronger.
* Cleanup/optimization
For when nothing is broken but something could be made cleaner,
better, faster, stronger.
Tickets should also be classified into *components* indicating which area of
the Django codebase they belong to. This makes tickets better organized and
@ -243,57 +247,57 @@ leave a comment with your thoughts instead.
If you do close a ticket, you should always make sure of the following:
* Be certain that the issue is resolved.
* Be certain that the issue is resolved.
* Leave a comment explaining the decision to close the ticket.
* Leave a comment explaining the decision to close the ticket.
* If there is a way they can improve the ticket to reopen it, let them know.
* If there is a way they can improve the ticket to reopen it, let them know.
* If the ticket is a duplicate, reference the original ticket. Also
cross-reference the closed ticket by leaving a comment in the original one
-- this allows to access more related information about the reported bug
or requested feature.
* If the ticket is a duplicate, reference the original ticket. Also
cross-reference the closed ticket by leaving a comment in the original one
-- this allows to access more related information about the reported bug
or requested feature.
* **Be polite.** No one likes having their ticket closed. It can be
frustrating or even discouraging. The best way to avoid turning people
off from contributing to Django is to be polite and friendly and to offer
suggestions for how they could improve this ticket and other tickets in
the future.
* **Be polite.** No one likes having their ticket closed. It can be
frustrating or even discouraging. The best way to avoid turning people
off from contributing to Django is to be polite and friendly and to offer
suggestions for how they could improve this ticket and other tickets in
the future.
A ticket can be resolved in a number of ways:
* fixed
Used by the core developers once a patch has been rolled into
Django and the issue is fixed.
* fixed
Used by the core developers once a patch has been rolled into
Django and the issue is fixed.
* invalid
Used if the ticket is found to be incorrect. This means that the
issue in the ticket is actually the result of a user error, or
describes a problem with something other than Django, or isn't
a bug report or feature request at all (for example, some new users
submit support queries as tickets).
* invalid
Used if the ticket is found to be incorrect. This means that the
issue in the ticket is actually the result of a user error, or
describes a problem with something other than Django, or isn't
a bug report or feature request at all (for example, some new users
submit support queries as tickets).
* wontfix
Used when a core developer decides that this request is not
appropriate for consideration in Django. This is usually chosen after
discussion in the `django-developers`_ mailing list. Feel free to
start or join in discussions of "wontfix" tickets on the
django-developers_ mailing list, but please do not reopen tickets
closed as "wontfix" by a :doc:`core developer</internals/committers>`.
* wontfix
Used when a core developer decides that this request is not
appropriate for consideration in Django. This is usually chosen after
discussion in the `django-developers`_ mailing list. Feel free to
start or join in discussions of "wontfix" tickets on the
django-developers_ mailing list, but please do not reopen tickets
closed as "wontfix" by a :doc:`core developer</internals/committers>`.
* duplicate
Used when another ticket covers the same issue. By closing duplicate
tickets, we keep all the discussion in one place, which helps
everyone.
* duplicate
Used when another ticket covers the same issue. By closing duplicate
tickets, we keep all the discussion in one place, which helps
everyone.
* worksforme
Used when the ticket doesn't contain enough detail to replicate
the original bug.
* worksforme
Used when the ticket doesn't contain enough detail to replicate
the original bug.
* needsinfo
Used when the ticket does not contain enough information to replicate
the reported issue but is potentially still valid. The ticket
should be reopened when more information is supplied.
* needsinfo
Used when the ticket does not contain enough information to replicate
the reported issue but is potentially still valid. The ticket
should be reopened when more information is supplied.
If you believe that the ticket was closed in error -- because you're
still having the issue, or it's popped up somewhere else, or the triagers have
@ -315,39 +319,39 @@ forgotten your password, you can reset it using the `password reset page`_.
Then, you can help out by:
* Closing "Unreviewed" tickets as "invalid", "worksforme" or "duplicate."
* Closing "Unreviewed" tickets as "invalid", "worksforme" or "duplicate."
* Promoting "Unreviewed" tickets to "Design decision needed" if a design
decision needs to be made, or "Accepted" in case of obvious bugs or
sensible, clearly defined, feature requests.
* Promoting "Unreviewed" tickets to "Design decision needed" if a design
decision needs to be made, or "Accepted" in case of obvious bugs or
sensible, clearly defined, feature requests.
* Correcting the "Needs tests", "Needs documentation", or "Has patch"
flags for tickets where they are incorrectly set.
* Correcting the "Needs tests", "Needs documentation", or "Has patch"
flags for tickets where they are incorrectly set.
* Setting the "`Easy pickings`_" flag for tickets that are small and
relatively straightforward.
* Setting the "`Easy pickings`_" flag for tickets that are small and
relatively straightforward.
* Checking that old tickets are still valid. If a ticket hasn't seen
any activity in a long time, it's possible that the problem has been
fixed but the ticket hasn't yet been closed.
* Checking that old tickets are still valid. If a ticket hasn't seen
any activity in a long time, it's possible that the problem has been
fixed but the ticket hasn't yet been closed.
* Contacting the owners of tickets that have been claimed but have not
seen any recent activity. If the owner doesn't respond after a week
or so, remove the owner's claim on the ticket.
* Contacting the owners of tickets that have been claimed but have not
seen any recent activity. If the owner doesn't respond after a week
or so, remove the owner's claim on the ticket.
* Identifying trends and themes in the tickets. If there a lot of bug
reports about a particular part of Django, it may indicate we should
consider refactoring that part of the code. If a trend is emerging,
you should raise it for discussion (referencing the relevant tickets)
on `django-developers`_.
* Identifying trends and themes in the tickets. If there a lot of bug
reports about a particular part of Django, it may indicate we should
consider refactoring that part of the code. If a trend is emerging,
you should raise it for discussion (referencing the relevant tickets)
on `django-developers`_.
* Set the *type* of tickets that are still uncategorized.
* Set the *type* of tickets that are still uncategorized.
* Verify if patches submitted by other users are correct. If they do and
also contain appropriate documentation and tests then move them to the
"Ready for Checkin" stage. If they don't then leave a comment to explain
why and set the corresponding flags ("Patch needs improvement",
"Needs tests" etc.).
* Verify if patches submitted by other users are correct. If they do and
also contain appropriate documentation and tests then move them to the
"Ready for Checkin" stage. If they don't then leave a comment to explain
why and set the corresponding flags ("Patch needs improvement",
"Needs tests" etc.).
.. note::
@ -362,23 +366,23 @@ Then, you can help out by:
However, we do ask the following of all general community members working in
the ticket database:
* Please **don't** close tickets as "wontfix." The core developers will
make the final determination of the fate of a ticket, usually after
consultation with the community.
* Please **don't** close tickets as "wontfix." The core developers will
make the final determination of the fate of a ticket, usually after
consultation with the community.
* Please **don't** promote your own tickets to "Ready for checkin". You
may mark other people's tickets which you've reviewed as "Ready for
checkin", but you should get at minimum one other community member to
review a patch that you submit.
* Please **don't** promote your own tickets to "Ready for checkin". You
may mark other people's tickets which you've reviewed as "Ready for
checkin", but you should get at minimum one other community member to
review a patch that you submit.
* Please **don't** reverse a decision that has been made by a :doc:`core
developer</internals/committers>`. If you disagree with a decision that
has been made, please post a message to `django-developers`_.
* Please **don't** reverse a decision that has been made by a :doc:`core
developer</internals/committers>`. If you disagree with a decision that
has been made, please post a message to `django-developers`_.
* If you're unsure if you should be making a change, don't make the
change but instead leave a comment with your concerns on the ticket,
or post a message to `django-developers`_. It's okay to be unsure,
but your input is still valuable.
* If you're unsure if you should be making a change, don't make the
change but instead leave a comment with your concerns on the ticket,
or post a message to `django-developers`_. It's okay to be unsure,
but your input is still valuable.
.. _Trac: http://code.djangoproject.com/
.. _django-developers: http://groups.google.com/group/django-developers

70
docs/internals/contributing/writing-code/branch-policy.txt
View file

@ -14,31 +14,31 @@ take more than a single patch, or requires large-scale refactoring -- you need
to do it on a feature branch. Our development process recognizes two options
for feature branches:
1. Feature branches using a distributed revision control system like
Git_, Mercurial_, Bazaar_, etc.
1. Feature branches using a distributed revision control system like
Git_, Mercurial_, Bazaar_, etc.
If you're familiar with one of these tools, this is probably your best
option since it doesn't require any support or buy-in from the Django
core developers.
If you're familiar with one of these tools, this is probably your best
option since it doesn't require any support or buy-in from the Django
core developers.
However, do keep in mind that Django will continue to use Subversion
for the foreseeable future, and this will naturally limit the
recognition of your branch. Further, if your branch becomes eligible
for merging to trunk you'll need to find a core developer familiar
with your DVCS of choice who'll actually perform the merge.
However, do keep in mind that Django will continue to use Subversion
for the foreseeable future, and this will naturally limit the
recognition of your branch. Further, if your branch becomes eligible
for merging to trunk you'll need to find a core developer familiar
with your DVCS of choice who'll actually perform the merge.
If you do decided to start a distributed branch of Django and choose to
make it public, please add the branch to the `Django branches`_ wiki
page.
If you do decided to start a distributed branch of Django and choose to
make it public, please add the branch to the `Django branches`_ wiki
page.
2. Feature branches using SVN have a higher bar. If you want a branch
in SVN itself, you'll need a "mentor" among the :doc:`core committers
</internals/committers>`. This person is responsible for actually
creating the branch, monitoring your process (see below), and
ultimately merging the branch into trunk.
2. Feature branches using SVN have a higher bar. If you want a branch
in SVN itself, you'll need a "mentor" among the :doc:`core committers
</internals/committers>`. This person is responsible for actually
creating the branch, monitoring your process (see below), and
ultimately merging the branch into trunk.
If you want a feature branch in SVN, you'll need to ask in
`django-developers`_ for a mentor.
If you want a feature branch in SVN, you'll need to ask in
`django-developers`_ for a mentor.
.. _git: http://git-scm.com/
.. _mercurial: http://mercurial.selenic.com/
@ -60,21 +60,21 @@ Developers with branches in SVN, however, **must** follow these rules. The
branch mentor will keep on eye on the branch and **will delete it** if these
rules are broken.
* Only branch entire copies of the Django tree, even if work is only
happening on part of that tree. This makes it painless to switch to a
branch.
* Only branch entire copies of the Django tree, even if work is only
happening on part of that tree. This makes it painless to switch to a
branch.
* Merge changes from trunk no less than once a week, and preferably every
couple-three days.
* Merge changes from trunk no less than once a week, and preferably every
couple-three days.
In our experience, doing regular trunk merges is often the difference
between a successful branch and one that fizzles and dies.
In our experience, doing regular trunk merges is often the difference
between a successful branch and one that fizzles and dies.
If you're working on an SVN branch, you should be using `svnmerge.py`_
to track merges from trunk.
If you're working on an SVN branch, you should be using `svnmerge.py`_
to track merges from trunk.
* Keep tests passing and documentation up-to-date. As with patches,
we'll only merge a branch that comes with tests and documentation.
* Keep tests passing and documentation up-to-date. As with patches,
we'll only merge a branch that comes with tests and documentation.
.. _svnmerge.py: http://www.orcaware.com/svn/wiki/Svnmerge.py
@ -91,11 +91,11 @@ Using branches
To use a branch, you'll need to do two things:
* Get the branch's code through Subversion.
* Get the branch's code through Subversion.
* Point your Python ``site-packages`` directory at the branch's version of
the ``django`` package rather than the version you already have
installed.
* Point your Python ``site-packages`` directory at the branch's version of
the ``django`` package rather than the version you already have
installed.
Getting the code from Subversion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

202
docs/internals/contributing/writing-code/coding-style.txt
View file

@ -7,137 +7,137 @@ Please follow these coding standards when writing code for inclusion in Django.
Python style
------------
* Unless otherwise specified, follow :pep:`8`.
* Unless otherwise specified, follow :pep:`8`.
You could use a tool like `pep8`_ to check for some problems in this
area, but remember that :pep:`8` is only a guide, so respect the style of
the surrounding code as a primary goal.
You could use a tool like `pep8`_ to check for some problems in this
area, but remember that :pep:`8` is only a guide, so respect the style of
the surrounding code as a primary goal.
* Use four spaces for indentation.
* Use four spaces for indentation.
* Use underscores, not camelCase, for variable, function and method names
(i.e. ``poll.get_unique_voters()``, not ``poll.getUniqueVoters``).
* Use underscores, not camelCase, for variable, function and method names
(i.e. ``poll.get_unique_voters()``, not ``poll.getUniqueVoters``).
* Use ``InitialCaps`` for class names (or for factory functions that
return classes).
* Use ``InitialCaps`` for class names (or for factory functions that
return classes).
* In docstrings, use "action words" such as::
* In docstrings, use "action words" such as::
def foo():
"""
Calculates something and returns the result.
"""
pass
def foo():
"""
Calculates something and returns the result.
"""
pass
Here's an example of what not to do::
Here's an example of what not to do::
def foo():
"""
Calculate something and return the result.
"""
pass
def foo():
"""
Calculate something and return the result.
"""
pass
Template style
--------------
* In Django template code, put one (and only one) space between the curly
brackets and the tag contents.
* In Django template code, put one (and only one) space between the curly
brackets and the tag contents.
Do this:
Do this:
.. code-block:: html+django
.. code-block:: html+django
{{ foo }}
{{ foo }}
Don't do this:
Don't do this:
.. code-block:: html+django
.. code-block:: html+django
{{foo}}
{{foo}}
View style
----------
* In Django views, the first parameter in a view function should be called
``request``.
* In Django views, the first parameter in a view function should be called
``request``.
Do this::
Do this::
def my_view(request, foo):
# ...
def my_view(request, foo):
# ...
Don't do this::
Don't do this::
def my_view(req, foo):
# ...
def my_view(req, foo):
# ...
Model style
-----------
* Field names should be all lowercase, using underscores instead of
camelCase.
* Field names should be all lowercase, using underscores instead of
camelCase.
Do this::
Do this::
class Person(models.Model):
first_name = models.CharField(max_length=20)
last_name = models.CharField(max_length=40)
class Person(models.Model):
first_name = models.CharField(max_length=20)
last_name = models.CharField(max_length=40)
Don't do this::
Don't do this::
class Person(models.Model):
FirstName = models.CharField(max_length=20)
Last_Name = models.CharField(max_length=40)
class Person(models.Model):
FirstName = models.CharField(max_length=20)
Last_Name = models.CharField(max_length=40)
* The ``class Meta`` should appear *after* the fields are defined, with
a single blank line separating the fields and the class definition.
* The ``class Meta`` should appear *after* the fields are defined, with
a single blank line separating the fields and the class definition.
Do this::
Do this::
class Person(models.Model):
first_name = models.CharField(max_length=20)
last_name = models.CharField(max_length=40)
class Person(models.Model):
first_name = models.CharField(max_length=20)
last_name = models.CharField(max_length=40)
class Meta:
verbose_name_plural = 'people'
class Meta:
verbose_name_plural = 'people'
Don't do this::
Don't do this::
class Person(models.Model):
first_name = models.CharField(max_length=20)
last_name = models.CharField(max_length=40)
class Meta:
verbose_name_plural = 'people'
class Person(models.Model):
first_name = models.CharField(max_length=20)
last_name = models.CharField(max_length=40)
class Meta:
verbose_name_plural = 'people'
Don't do this, either::
Don't do this, either::
class Person(models.Model):
class Meta:
verbose_name_plural = 'people'
class Person(models.Model):
class Meta:
verbose_name_plural = 'people'
first_name = models.CharField(max_length=20)
last_name = models.CharField(max_length=40)
first_name = models.CharField(max_length=20)
last_name = models.CharField(max_length=40)
* The order of model inner classes and standard methods should be as
follows (noting that these are not all required):
* The order of model inner classes and standard methods should be as
follows (noting that these are not all required):
* All database fields
* Custom manager attributes
* ``class Meta``
* ``def __unicode__()``
* ``def __str__()``
* ``def save()``
* ``def get_absolute_url()``
* Any custom methods
* All database fields
* Custom manager attributes
* ``class Meta``
* ``def __unicode__()``
* ``def __str__()``
* ``def save()``
* ``def get_absolute_url()``
* Any custom methods
* If ``choices`` is defined for a given model field, define the choices as
a tuple of tuples, with an all-uppercase name, either near the top of
the model module or just above the model class. Example::
* If ``choices`` is defined for a given model field, define the choices as
a tuple of tuples, with an all-uppercase name, either near the top of
the model module or just above the model class. Example::
GENDER_CHOICES = (
('M', 'Male'),
('F', 'Female'),
)
GENDER_CHOICES = (
('M', 'Male'),
('F', 'Female'),
)
Use of ``django.conf.settings``
-------------------------------
@ -178,26 +178,26 @@ as :class:`django.utils.functional.LazyObject`,
Miscellaneous
-------------
* Mark all strings for internationalization; see the :doc:`i18n
documentation </topics/i18n/index>` for details.
* Mark all strings for internationalization; see the :doc:`i18n
documentation </topics/i18n/index>` for details.
* Remove ``import`` statements that are no longer used when you change code.
The most common tools for this task are `pyflakes`_ and `pylint`_.
* Remove ``import`` statements that are no longer used when you change code.
The most common tools for this task are `pyflakes`_ and `pylint`_.
* Systematically remove all trailing whitespaces from your code as those
add unnecessary bytes, add visual clutter to the patches and can also
occasionally cause unnecessary merge conflicts. Some IDE's can be
configured to automatically remove them and most VCS tools can be set to
highlight them in diff outputs. Note, however, that patches which only
remove whitespace (or only make changes for nominal PEP 8 conformance)
are likely to be rejected, since they only introduce noise rather than
code improvement. Tidy up when you're next changing code in the area.
* Systematically remove all trailing whitespaces from your code as those
add unnecessary bytes, add visual clutter to the patches and can also
occasionally cause unnecessary merge conflicts. Some IDE's can be
configured to automatically remove them and most VCS tools can be set to
highlight them in diff outputs. Note, however, that patches which only
remove whitespace (or only make changes for nominal PEP 8 conformance)
are likely to be rejected, since they only introduce noise rather than
code improvement. Tidy up when you're next changing code in the area.
* Please don't put your name in the code you contribute. Our policy is to
keep contributors' names in the ``AUTHORS`` file distributed with Django
-- not scattered throughout the codebase itself. Feel free to include a
change to the ``AUTHORS`` file in your patch if you make more than a
single trivial change.
* Please don't put your name in the code you contribute. Our policy is to
keep contributors' names in the ``AUTHORS`` file distributed with Django
-- not scattered throughout the codebase itself. Feel free to include a
change to the ``AUTHORS`` file in your patch if you make more than a
single trivial change.
.. _pep8: http://pypi.python.org/pypi/pep8
.. _pyflakes: http://pypi.python.org/pypi/pyflakes

92
docs/internals/contributing/writing-code/submitting-patches.txt
View file

@ -19,28 +19,28 @@ If you have identified a contribution you want to make and you're capable of
fixing it (as measured by your coding ability, knowledge of Django internals
and time availability), claim it by following these steps:
* `Create an account`_ to use in our ticket system. If you have an account
but have forgotten your password, you can reset it using the
`password reset page`_.
* `Create an account`_ to use in our ticket system. If you have an account
but have forgotten your password, you can reset it using the
`password reset page`_.
* If a ticket for this issue doesn't exist yet, create one in our
`ticket tracker`_.
* If a ticket for this issue doesn't exist yet, create one in our
`ticket tracker`_.
* If a ticket for this issue already exists, make sure nobody else has
claimed it. To do this, look at the "Assigned to" section of the ticket.
If it's assigned to "nobody," then it's available to be claimed.
Otherwise, somebody else is working on this ticket, and you either find
another bug/feature to work on, or contact the developer working on the
ticket to offer your help.
* If a ticket for this issue already exists, make sure nobody else has
claimed it. To do this, look at the "Assigned to" section of the ticket.
If it's assigned to "nobody," then it's available to be claimed.
Otherwise, somebody else is working on this ticket, and you either find
another bug/feature to work on, or contact the developer working on the
ticket to offer your help.
* Log into your account, if you haven't already, by clicking "Login" in
the upper right of the ticket page.
* Log into your account, if you haven't already, by clicking "Login" in
the upper right of the ticket page.
* Claim the ticket:
* Claim the ticket:
1. click the "accept" radio button under "Action" near the bottom of the
page,
2. then click "Submit changes."
1. click the "accept" radio button under "Action" near the bottom of the
page,
2. then click "Submit changes."
.. _Create an account: https://www.djangoproject.com/accounts/register/
.. _password reset page: https://www.djangoproject.com/accounts/password/reset/
@ -76,43 +76,43 @@ it.
Patch style
-----------
* Make sure your code matches our :doc:`coding-style`.
* Make sure your code matches our :doc:`coding-style`.
* Submit patches in the format returned by the ``svn diff`` command.
An exception is for code changes that are described more clearly in
plain English than in code. Indentation is the most common example; it's
hard to read patches when the only difference in code is that it's
indented.
* Submit patches in the format returned by the ``svn diff`` command.
An exception is for code changes that are described more clearly in
plain English than in code. Indentation is the most common example; it's
hard to read patches when the only difference in code is that it's
indented.
Patches in ``git diff`` format are also acceptable.
Patches in ``git diff`` format are also acceptable.
* When creating patches, always run ``svn diff`` from the top-level
``trunk`` directory -- i.e. the one that contains ``django``, ``docs``,
``tests``, ``AUTHORS``, etc. This makes it easy for other people to
apply your patches.
* When creating patches, always run ``svn diff`` from the top-level
``trunk`` directory -- i.e. the one that contains ``django``, ``docs``,
``tests``, ``AUTHORS``, etc. This makes it easy for other people to
apply your patches.
* Attach patches to a ticket in the `ticket tracker`_, using the "attach
file" button. Please *don't* put the patch in the ticket description
or comment unless it's a single line patch.
* Attach patches to a ticket in the `ticket tracker`_, using the "attach
file" button. Please *don't* put the patch in the ticket description
or comment unless it's a single line patch.
* Name the patch file with a ``.diff`` extension; this will let the ticket
tracker apply correct syntax highlighting, which is quite helpful.
* Name the patch file with a ``.diff`` extension; this will let the ticket
tracker apply correct syntax highlighting, which is quite helpful.
* Check the "Has patch" box on the ticket details. This will make it
obvious that the ticket includes a patch, and it will add the ticket to
the `list of tickets with patches`_.
* Check the "Has patch" box on the ticket details. This will make it
obvious that the ticket includes a patch, and it will add the ticket to
the `list of tickets with patches`_.
* The code required to fix a problem or add a feature is an essential part
of a patch, but it is not the only part. A good patch should also
include a regression test to validate the behavior that has been fixed
and to prevent the problem from arising again. Also, if some tickets are
relevant to the code that you've written, mention the ticket numbers in
some comments in the test so that one can easily trace back the relevant
discussions after your patch gets committed and the tickets get closed.
* The code required to fix a problem or add a feature is an essential part
of a patch, but it is not the only part. A good patch should also
include a regression test to validate the behavior that has been fixed
and to prevent the problem from arising again. Also, if some tickets are
relevant to the code that you've written, mention the ticket numbers in
some comments in the test so that one can easily trace back the relevant
discussions after your patch gets committed and the tickets get closed.
* If the code associated with a patch adds a new feature, or modifies
behavior of an existing feature, the patch should also contain
documentation.
* If the code associated with a patch adds a new feature, or modifies
behavior of an existing feature, the patch should also contain
documentation.
Non-trivial patches
-------------------

54
docs/internals/contributing/writing-code/unit-tests.txt
View file

@ -7,9 +7,9 @@ code base. It's our policy to make sure all tests pass at all times.
The tests cover:
* Models and the database API (``tests/modeltests``),
* Everything else in core Django code (``tests/regressiontests``),
* :ref:`contrib-apps` (``django/contrib/<app>/tests``).
* Models and the database API (``tests/modeltests``),
* Everything else in core Django code (``tests/regressiontests``),
* :ref:`contrib-apps` (``django/contrib/<app>/tests``).
We appreciate any and all contributions to the test suite!
@ -58,30 +58,30 @@ and type:
The :setting:`DATABASES` setting in this test settings module needs to define
two databases:
* A ``default`` database. This database should use the backend that
you want to use for primary testing
* A ``default`` database. This database should use the backend that
you want to use for primary testing
* A database with the alias ``other``. The ``other`` database is
used to establish that queries can be directed to different
databases. As a result, this database can use any backend you
want. It doesn't need to use the same backend as the ``default``
database (although it can use the same backend if you want to).
* A database with the alias ``other``. The ``other`` database is
used to establish that queries can be directed to different
databases. As a result, this database can use any backend you
want. It doesn't need to use the same backend as the ``default``
database (although it can use the same backend if you want to).
If you're using a backend that isn't SQLite, you will need to provide other
details for each database:
* The :setting:`USER` option for each of your databases needs to
specify an existing user account for the database.
* The :setting:`USER` option for each of your databases needs to
specify an existing user account for the database.
* The :setting:`PASSWORD` option needs to provide the password for
the :setting:`USER` that has been specified.
* The :setting:`PASSWORD` option needs to provide the password for
the :setting:`USER` that has been specified.
* The :setting:`NAME` option must be the name of an existing database to
which the given user has permission to connect. The unit tests will not
touch this database; the test runner creates a new database whose name
is :setting:`NAME` prefixed with ``test_``, and this test database is
deleted when the tests are finished. This means your user account needs
permission to execute ``CREATE DATABASE``.
* The :setting:`NAME` option must be the name of an existing database to
which the given user has permission to connect. The unit tests will not
touch this database; the test runner creates a new database whose name
is :setting:`NAME` prefixed with ``test_``, and this test database is
deleted when the tests are finished. This means your user account needs
permission to execute ``CREATE DATABASE``.
You will also need to ensure that your database uses UTF-8 as the default
character set. If your database server doesn't use UTF-8 as a default charset,
@ -128,13 +128,13 @@ Running all the tests
If you want to run the full suite of tests, you'll need to install a number of
dependencies:
* PyYAML_
* Markdown_
* Textile_
* Docutils_
* setuptools_
* memcached_, plus a :ref:`supported Python binding <memcached>`
* gettext_ (:ref:`gettext_on_windows`)
* PyYAML_
* Markdown_
* Textile_
* Docutils_
* setuptools_
* memcached_, plus a :ref:`supported Python binding <memcached>`
* gettext_ (:ref:`gettext_on_windows`)
If you want to test the memcached cache backend, you'll also need to define
a :setting:`CACHES` setting that points at your memcached instance.

260
docs/internals/contributing/writing-documentation.txt
View file

@ -9,11 +9,11 @@ possible.
Documentation changes generally come in two forms:
* General improvements: typo corrections, error fixes and better
explanations through clearer writing and more examples.
* General improvements: typo corrections, error fixes and better
explanations through clearer writing and more examples.
* New features: documentation of features that have been added to the
framework since the last release.
* New features: documentation of features that have been added to the
framework since the last release.
This section explains how writers can craft their documentation changes
in the most useful and least error-prone ways.
@ -54,37 +54,37 @@ Commonly used terms
Here are some style guidelines on commonly used terms throughout the
documentation:
* **Django** -- when referring to the framework, capitalize Django. It is
lowercase only in Python code and in the djangoproject.com logo.
* **Django** -- when referring to the framework, capitalize Django. It is
lowercase only in Python code and in the djangoproject.com logo.
* **email** -- no hyphen.
* **email** -- no hyphen.
* **MySQL**, **PostgreSQL**, **SQLite**
* **MySQL**, **PostgreSQL**, **SQLite**
* **Python** -- when referring to the language, capitalize Python.
* **Python** -- when referring to the language, capitalize Python.
* **realize**, **customize**, **initialize**, etc. -- use the American
"ize" suffix, not "ise."
* **realize**, **customize**, **initialize**, etc. -- use the American
"ize" suffix, not "ise."
* **subclass** -- it's a single word without a hyphen, both as a verb
("subclass that model") and as a noun ("create a subclass").
* **subclass** -- it's a single word without a hyphen, both as a verb
("subclass that model") and as a noun ("create a subclass").
* **Web**, **World Wide Web**, **the Web** -- note Web is always
capitalized when referring to the World Wide Web.
* **Web**, **World Wide Web**, **the Web** -- note Web is always
capitalized when referring to the World Wide Web.
* **Web site** -- use two words, with Web capitalized.
* **Web site** -- use two words, with Web capitalized.
Django-specific terminology
---------------------------
* **model** -- it's not capitalized.
* **model** -- it's not capitalized.
* **template** -- it's not capitalized.
* **template** -- it's not capitalized.
* **URLconf** -- use three capitalized letters, with no space before
"conf."
* **URLconf** -- use three capitalized letters, with no space before
"conf."
* **view** -- it's not capitalized.
* **view** -- it's not capitalized.
Guidelines for reStructuredText files
-------------------------------------
@ -92,27 +92,27 @@ Guidelines for reStructuredText files
These guidelines regulate the format of our reST (reStructuredText)
documentation:
* In section titles, capitalize only initial words and proper nouns.
* In section titles, capitalize only initial words and proper nouns.
* Wrap the documentation at 80 characters wide, unless a code example
is significantly less readable when split over two lines, or for another
good reason.
* Wrap the documentation at 80 characters wide, unless a code example
is significantly less readable when split over two lines, or for another
good reason.
* The main thing to keep in mind as you write and edit docs is that the
more semantic markup you can add the better. So::
* The main thing to keep in mind as you write and edit docs is that the
more semantic markup you can add the better. So::
Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
Isn't nearly as helpful as::
Isn't nearly as helpful as::
Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
This is because Sphinx will generate proper links for the latter, which
greatly helps readers. There's basically no limit to the amount of
useful markup you can add.
This is because Sphinx will generate proper links for the latter, which
greatly helps readers. There's basically no limit to the amount of
useful markup you can add.
* Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx'
documentation.
* Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx'
documentation.
Django-specific markup
----------------------
@ -122,41 +122,41 @@ description units:
__ http://sphinx.pocoo.org/markup/desc.html
* Settings::
* Settings::
.. setting:: INSTALLED_APPS
.. setting:: INSTALLED_APPS
To link to a setting, use ``:setting:`INSTALLED_APPS```.
To link to a setting, use ``:setting:`INSTALLED_APPS```.
* Template tags::
* Template tags::
.. templatetag:: regroup
.. templatetag:: regroup
To link, use ``:ttag:`regroup```.
To link, use ``:ttag:`regroup```.
* Template filters::
* Template filters::
.. templatefilter:: linebreaksbr
.. templatefilter:: linebreaksbr
To link, use ``:tfilter:`linebreaksbr```.
To link, use ``:tfilter:`linebreaksbr```.
* Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``)::
* Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``)::
.. fieldlookup:: exact
.. fieldlookup:: exact
To link, use ``:lookup:`exact```.
To link, use ``:lookup:`exact```.
* ``django-admin`` commands::
* ``django-admin`` commands::
.. django-admin:: syncdb
.. django-admin:: syncdb
To link, use ``:djadmin:`syncdb```.
To link, use ``:djadmin:`syncdb```.
* ``django-admin`` command-line options::
* ``django-admin`` command-line options::
.. django-admin-option:: --traceback
.. django-admin-option:: --traceback
To link, use ``:djadminopt:`--traceback```.
To link, use ``:djadminopt:`--traceback```.
.. _documenting-new-features:
@ -184,68 +184,68 @@ An example
For a quick example of how it all fits together, consider this hypothetical
example:
* First, the ``ref/settings.txt`` document could have an overall layout
like this:
* First, the ``ref/settings.txt`` document could have an overall layout
like this:
.. code-block:: rst
.. code-block:: rst
========
Settings
========
========
Settings
========
...
...
.. _available-settings:
.. _available-settings:
Available settings
==================
Available settings
==================
...
...
.. _deprecated-settings:
.. _deprecated-settings:
Deprecated settings
===================
Deprecated settings
===================
...
...
* Next, the ``topics/settings.txt`` document could contain something like
this:
* Next, the ``topics/settings.txt`` document could contain something like
this:
.. code-block:: rst
.. code-block:: rst
You can access a :ref:`listing of all available settings
<available-settings>`. For a list of deprecated settings see
:ref:`deprecated-settings`.
You can access a :ref:`listing of all available settings
<available-settings>`. For a list of deprecated settings see
:ref:`deprecated-settings`.
You can find both in the :doc:`settings reference document
</ref/settings>`.
You can find both in the :doc:`settings reference document
</ref/settings>`.
We use the Sphinx :rst:role:`doc` cross reference element when we want to
link to another document as a whole and the :rst:role:`ref` element when
we want to link to an arbitrary location in a document.
We use the Sphinx :rst:role:`doc` cross reference element when we want to
link to another document as a whole and the :rst:role:`ref` element when
we want to link to an arbitrary location in a document.
* Next, notice how the settings are annotated:
* Next, notice how the settings are annotated:
.. code-block:: rst
.. code-block:: rst
.. setting:: ADMIN_FOR
.. setting:: ADMIN_FOR
ADMIN_FOR
---------
ADMIN_FOR
---------
Default: ``()`` (Empty tuple)
Default: ``()`` (Empty tuple)
Used for admin-site settings modules, this should be a tuple of
settings modules (in the format ``'foo.bar.baz'``) for which this site
is an admin.
Used for admin-site settings modules, this should be a tuple of
settings modules (in the format ``'foo.bar.baz'``) for which this site
is an admin.
The admin site uses this in its automatically-introspected
documentation of models, views and template tags.
The admin site uses this in its automatically-introspected
documentation of models, views and template tags.
This marks up the following header as the "canonical" target for the
setting ``ADMIN_FOR`` This means any time I talk about ``ADMIN_FOR``,
I can reference it using ``:setting:`ADMIN_FOR```.
This marks up the following header as the "canonical" target for the
setting ``ADMIN_FOR`` This means any time I talk about ``ADMIN_FOR``,
I can reference it using ``:setting:`ADMIN_FOR```.
That's basically how everything fits together.
@ -257,57 +257,57 @@ Improving the documentation
A few small improvements can be made to make the documentation read and
look better:
* Most of the various ``index.txt`` documents have *very* short or even
non-existent intro text. Each of those documents needs a good short
intro the content below that point.
* Most of the various ``index.txt`` documents have *very* short or even
non-existent intro text. Each of those documents needs a good short
intro the content below that point.
* The glossary is very perfunctory. It needs to be filled out.
* The glossary is very perfunctory. It needs to be filled out.
* Add more metadata targets. Lots of places look like::
* Add more metadata targets. Lots of places look like::
``File.close()``
~~~~~~~~~~~~~~~~
``File.close()``
~~~~~~~~~~~~~~~~
\... these should be::
\... these should be::
.. method:: File.close()
.. method:: File.close()
That is, use metadata instead of titles.
That is, use metadata instead of titles.
* Add more links -- nearly everything that's an inline code literal
right now can probably be turned into a xref.
* Add more links -- nearly everything that's an inline code literal
right now can probably be turned into a xref.
See the ``literals_to_xrefs.py`` file in ``_ext`` -- it's a shell script
to help do this work.
See the ``literals_to_xrefs.py`` file in ``_ext`` -- it's a shell script
to help do this work.
This will probably be a continuing, never-ending project.
This will probably be a continuing, never-ending project.
* Add `info field lists`__ where appropriate.
* Add `info field lists`__ where appropriate.
__ http://sphinx.pocoo.org/markup/desc.html#info-field-lists
__ http://sphinx.pocoo.org/markup/desc.html#info-field-lists
* Whenever possible, use links. So, use ``:setting:`ADMIN_FOR``` instead
of ````ADMIN_FOR````.
* Whenever possible, use links. So, use ``:setting:`ADMIN_FOR``` instead
of ````ADMIN_FOR````.
* Use directives where appropriate. Some directives
(e.g. ``.. setting::``) are prefix-style directives; they go *before*
the unit they're describing. These are known as "crossref" directives.
Others (e.g. ``.. class::``) generate their own markup; these should go
inside the section they're describing. These are called
"description units".
* Use directives where appropriate. Some directives
(e.g. ``.. setting::``) are prefix-style directives; they go *before*
the unit they're describing. These are known as "crossref" directives.
Others (e.g. ``.. class::``) generate their own markup; these should go
inside the section they're describing. These are called
"description units".
You can tell which are which by looking at in
:file:`_ext/djangodocs.py`; it registers roles as one of the other.
You can tell which are which by looking at in
:file:`_ext/djangodocs.py`; it registers roles as one of the other.
* Add ``.. code-block:: <lang>`` to literal blocks so that they get
highlighted.
* Add ``.. code-block:: <lang>`` to literal blocks so that they get
highlighted.
* When referring to classes/functions/modules, etc., you'll want to use
the fully-qualified name of the target
(``:class:`django.contrib.contenttypes.models.ContentType```).
* When referring to classes/functions/modules, etc., you'll want to use
the fully-qualified name of the target
(``:class:`django.contrib.contenttypes.models.ContentType```).
Since this doesn't look all that awesome in the output -- it shows the
entire path to the object -- you can prefix the target with a ``~``
(that's a tilde) to get just the "last bit" of that path. So
``:class:`~django.contrib.contenttypes.models.ContentType``` will just
display a link with the title "ContentType".
Since this doesn't look all that awesome in the output -- it shows the
entire path to the object -- you can prefix the target with a ``~``
(that's a tilde) to get just the "last bit" of that path. So
``:class:`~django.contrib.contenttypes.models.ContentType``` will just
display a link with the title "ContentType".