Ticket #15796: 15796.contributing-doc-refactor.2.diff

File 15796.contributing-doc-refactor.2.diff, 159.0 KB (added by Julien Phalip, 13 years ago)

  • deleted file docs/howto/contribute.txt 

    diff --git a/docs/howto/contribute.txt b/docs/howto/contribute.txt
deleted file mode 100644
index 5d17ae6..0000000
    + -  
    1 ===========================
    2 How to contribute to Django
    3 ===========================
    4 
    5 Django is developed 100% by the community, and the more people that are actively
    6 involved in the code the better Django will be. We recognize that contributing
    7 to Django can be daunting at first and sometimes confusing even to
    8 veterans. While we have our official "Contributing to Django" documentation
    9 which spells out the technical details of triaging tickets and submitting
    10 patches, it leaves a lot of room for interpretation. This guide aims to offer
    11 more general advice on issues such as how to interpret the various stages and
    12 flags in Trac, and how new contributors can get started.
    13 
    14 .. seealso::
    15 
    16     This guide is meant to answer the most common questions about
    17     contributing to Django, however it is no substitute for the
    18     :doc:`/internals/contributing` reference. Please make sure to
    19     read that document to understand the specific details
    20     involved in reporting issues and submitting patches.
    21 
    22 .. _the-spirit-of-contributing:
    23 
    24 "The Spirit of Contributing"
    25 ============================
    26 
    27 Django uses Trac_ for managing our progress, and Trac is a community-tended
    28 garden of the bugs people have found and the features people would like to see
    29 added. As in any garden, sometimes there are weeds to be pulled and sometimes
    30 there are flowers and vegetables that need picking. We need your help to sort
    31 out one from the other, and in the end we all benefit together.
    32 
    33 Like all gardens, we can aspire to perfection but in reality there's no such
    34 thing. Even in the most pristine garden there are still snails and insects. In a
    35 community garden there are also helpful people who--with the best of
    36 intentions--fertilize the weeds and poison the roses. It's the job of the
    37 community as a whole to self-manage, keep the problems to a minimum, and educate
    38 those coming into the community so that they can become valuable contributing
    39 members.
    40 
    41 Similarly, while we aim for Trac to be a perfect representation of the state of
    42 Django's progress, we acknowledge that this simply will not happen. By
    43 distributing the load of Trac maintenance to the community, we accept that there
    44 will be mistakes. Trac is "mostly accurate", and we give allowances for the fact
    45 that sometimes it will be wrong. That's okay. We're perfectionists with
    46 deadlines.
    47 
    48 We rely on the community to keep participating, keep tickets as accurate as
    49 possible, and raise issues for discussion on our mailing lists when there is
    50 confusion or disagreement.
    51 
    52 Django is a community project, and every contribution helps. We can't do this
    53 without YOU!
    54 
    55 .. _Trac: http://code.djangoproject.com/
    56 
    57 Understanding Trac
    58 ==================
    59 
    60 Trac is Django's sole official issue tracker. All known bugs, desired features
    61 and ideas for changes are logged there.
    62 
    63 However, Trac can be quite confusing even to veteran contributors.  Having to
    64 look at both flags and triage stages isn't immediately obvious, and the stages
    65 themselves can be misinterpreted.
    66 
    67 .. _triage-stages-explained:
    68 
    69 What Django's triage stages "really mean"
    70 -----------------------------------------
    71 
    72 Unreviewed
    73 ~~~~~~~~~~
    74 
    75 The ticket has not been reviewed by anyone who felt qualified to make a judgment
    76 about whether the ticket contained a valid issue, a viable feature, or ought to
    77 be closed for any of the various reasons.
    78 
    79 Accepted
    80 ~~~~~~~~
    81 
    82 The big grey area! The absolute meaning of "accepted" is that the issue
    83 described in the ticket is valid and is in some stage of being worked on. Beyond
    84 that there are several considerations
    85 
    86 
    87 * **Accepted + No Flags**
    88 
    89   The ticket is valid, but no one has submitted a patch for it yet. Often this
    90   means you could safely start writing a patch for it.
    91 
    92 * **Accepted + Has Patch**
    93 
    94   The ticket is waiting for people to review the supplied patch. This means
    95   downloading the patch and trying it out, verifying that it contains tests and
    96   docs, running the test suite with the included patch, and leaving feedback on
    97   the ticket.
    98 
    99 
    100 * **Accepted + Has Patch + (any other flag)**
    101 
    102   This means the ticket has been reviewed, and has been found to need further
    103   work. "Needs tests" and "Needs documentation" are self-explanatory. "Patch
    104   needs improvement" will generally be accompanied by a comment on the ticket
    105   explaining what is needed to improve the code.
    106 
    107 Design Decision Needed
    108 ~~~~~~~~~~~~~~~~~~~~~~
    109 
    110 This stage is for issues which may be contentious, may be backwards
    111 incompatible, or otherwise involve high-level design decisions. These decisions
    112 are generally made by the core committers, however that is not a
    113 requirement. See the FAQ below for "My ticket has been in DDN forever!  What
    114 should I do?"
    115 
    116 Ready For Checkin
    117 ~~~~~~~~~~~~~~~~~
    118 
    119 The ticket was reviewed by any member of the community other than the person who
    120 supplied the patch and found to meet all the requirements for a commit-ready
    121 patch. A core committer now needs to give the patch a final review prior to
    122 being committed. See the FAQ below for "My ticket has been in RFC forever!  What
    123 should I do?"
    124 
    125 Someday/Maybe?
    126 ~~~~~~~~~~~~~~
    127 
    128 Generally only used for vague/high-level features or design ideas. These tickets
    129 are uncommon and overall less useful since they don't describe concrete
    130 actionable issues.
    131 
    132 Fixed on a branch
    133 ~~~~~~~~~~~~~~~~~
    134 
    135 Used to indicate that a ticket is resolved as part of a major body of work that
    136 will eventually be merged to trunk.  Tickets in this stage generally don't need
    137 further work. This may happen in the case of major features/refactors in each
    138 release cycle, or as part of the annual Google Summer of Code efforts.
    139 
    140 .. _closing-tickets:
    141 
    142 Closing Tickets
    143 ---------------
    144 
    145 When a ticket has completed its useful lifecycle, it's time for it to be closed.
    146 Closing a ticket is a big responsibility, though. You have to be sure that
    147 the issue is really resolved, and you need to keep in mind that the reporter
    148 of the ticket may not be happy to have their ticket closed (unless it's fixed,
    149 of course). If you're not certain about closing a ticket, just leave a comment
    150 with your thoughts instead.
    151 
    152 If you do close a ticket, you should always make sure of the following:
    153 
    154   * Be certain that the issue is resolved.
    155 
    156   * Leave a comment explaining the decision to close the ticket.
    157 
    158   * If there is a way they can improve the ticket to reopen it, let them know.
    159 
    160   * If the ticket is a duplicate, reference the original ticket.
    161 
    162   * **Be polite.** No one likes having their ticket closed. It can be
    163     frustrating or even discouraging. The best way to avoid turning people
    164     off from contributing to Django is to be polite and friendly and to offer
    165     suggestions for how they could improve this ticket and other tickets in the
    166     future.
    167 
    168 .. seealso::
    169 
    170     The :ref:`contributing reference <ticket-resolutions>` contains a
    171     description of each of the available resolutions in Trac.
    172 
    173 Example Trac workflow
    174 ---------------------
    175 
    176 Here we see the life-cycle of an average ticket:
    177 
    178 * Alice creates a ticket, and uploads an incomplete patch (no tests, incorrect
    179   implementation).
    180 
    181 * Bob reviews the patch, marks it "Accepted", "needs tests", and "patch needs
    182   improvement", and leaves a comment telling Alice how the patch could be
    183   improved.
    184 
    185 * Alice updates the patch, adding tests (but not changing the
    186   implementation). She removes the two flags.
    187 
    188 * Charlie reviews the patch and resets the "patch needs improvement" flag with
    189   another comment about improving the implementation.
    190 
    191 * Alice updates the patch, fixing the implementation. She removes the "patch
    192   needs improvement" flag.
    193 
    194 * Daisy reviews the patch, and marks it RFC.
    195 
    196 * Jacob reviews the RFC patch, applies it to his checkout, and commits it.
    197 
    198 Some tickets require much less feedback than this, but then again some tickets
    199 require much much more.
    200 
    201 Advice for new contributors
    202 ===========================
    203 
    204 New contributor and not sure what to do? Want to help but just don't know how to
    205 get started? This is the section for you.
    206 
    207 * **Pick a subject area that you care about, that you are familiar with, or that
    208   you want to learn about.**
    209 
    210   You don't already have to be an expert on the area you want to work on; you
    211   become an expert through your ongoing contributions to the code.
    212 
    213 * **Triage tickets.**
    214 
    215   If a ticket is unreviewed and reports a bug, try and duplicate it.  If you can
    216   duplicate it and it seems valid, make a note that you confirmed the bug and
    217   accept the ticket. Make sure the ticket is filed under the correct component
    218   area. Consider writing a patch that adds a test for the bug's behavior, even
    219   if you don't fix the bug itself.
    220 
    221 * **Look for tickets that are accepted and review patches to build familiarity
    222   with the codebase and the process.**
    223 
    224   Mark the appropriate flags if a patch needs docs or tests. Look through the
    225   changes a patch makes, and keep an eye out for syntax that is incompatible
    226   with older but still supported versions of Python. Run the tests and make sure
    227   they pass on your system.  Where possible and relevant, try them out on a
    228   database other than SQLite. Leave comments and feedback!
    229 
    230 * **Keep old patches up to date.**
    231 
    232   Oftentimes the codebase will change between a patch being submitted and the
    233   time it gets reviewed. Make sure it still applies cleanly and functions as
    234   expected. Simply updating a patch is both useful and important!
    235 
    236 * **Trac isn't an absolute; the context is just as important as the words.**
    237 
    238   When reading Trac, you need to take into account who says things, and when
    239   they were said. Support for an idea two years ago doesn't necessarily mean
    240   that the idea will still have support. You also need to pay attention to who
    241   *hasn't* spoken -- for example, if a core team member hasn't been recently
    242   involved in a discussion, then a ticket may not have the support required to
    243   get into trunk.
    244 
    245 * **Start small.**
    246 
    247   It's easier to get feedback on a little issue than on a big one.
    248 
    249 * **If you're going to engage in a big task, make sure that your idea has
    250   support first.**
    251 
    252   This means getting someone else to confirm that a bug is real before you fix
    253   the issue, and ensuring that the core team supports a proposed feature before
    254   you go implementing it.
    255 
    256 * **Be bold! Leave feedback!**
    257 
    258   Sometimes it can be scary to put your opinion out to the world and say "this
    259   ticket is correct" or "this patch needs work", but it's the only way the
    260   project moves forward. The contributions of the broad Django community
    261   ultimately have a much greater impact than that of the core developers. We
    262   can't do it without YOU!
    263 
    264 * **Err on the side of caution when marking things Ready For Check-in.**
    265 
    266   If you're really not certain if a ticket is ready, don't mark it as
    267   such. Leave a comment instead, letting others know your thoughts.  If you're
    268   mostly certain, but not completely certain, you might also try asking on IRC
    269   to see if someone else can confirm your suspicions.
    270 
    271 * **Wait for feedback, and respond to feedback that you receive.**
    272 
    273   Focus on one or two tickets, see them through from start to finish, and
    274   repeat. The shotgun approach of taking on lots of tickets and letting some
    275   fall by the wayside ends up doing more harm than good.
    276 
    277 * **Be rigorous.**
    278 
    279   When we say ":pep:`8`, and must have docs and tests", we mean it. If a patch
    280   doesn't have docs and tests, there had better be a good reason. Arguments like
    281   "I couldn't find any existing tests of this feature" don't carry much
    282   weight--while it may be true, that means you have the extra-important job of
    283   writing the very first tests for that feature, not that you get a pass from
    284   writing tests altogether.
    285 
    286 .. note::
    287 
    288     The `Reports page`_ contains links to many useful Trac queries, including
    289     several that are useful for triaging tickets and reviewing patches as
    290     suggested above.
    291 
    292     .. _Reports page: http://code.djangoproject.com/wiki/Reports
    293 
    294 
    295 FAQs
    296 ====
    297 
    298 **This ticket I care about has been ignored for days/weeks/months! What can I do
    299 to get it committed?**
    300 
    301 * First off, it's not personal. Django is entirely developed by volunteers (even
    302   the core devs), and sometimes folks just don't have time. The best thing to do
    303   is to send a gentle reminder to the Django Developers mailing list asking for
    304   review on the ticket, or to bring it up in the #django-dev IRC channel.
    305 
    306 
    307 **I'm sure my ticket is absolutely 100% perfect, can I mark it as RFC myself?**
    308 
    309 * Short answer: No. It's always better to get another set of eyes on a
    310   ticket. If you're having trouble getting that second set of eyes, see question
    311   1, above.
    312 
    313 
    314 **My ticket has been in DDN forever! What should I do?**
    315 
    316 * Design Decision Needed requires consensus about the right solution.  At the
    317   very least it needs consensus among the core developers, and ideally it has
    318   consensus from the community as well. The best way to accomplish this is to
    319   start a thread on the Django Developers mailing list, and for very complex
    320   issues to start a wiki page summarizing the problem and the possible
    321   solutions.

  • docs/howto/index.txt 

    diff --git a/docs/howto/index.txt b/docs/howto/index.txt
index 7ce7d26..49d0644 100644
    a b you quickly accomplish common tasks.  
    1111
    1212   apache-auth
    1313   auth-remote-user
    14    contribute
    1514   custom-management-commands
    1615   custom-model-fields
    1716   custom-template-tags

  • docs/index.txt 

    diff --git a/docs/index.txt b/docs/index.txt
index 9135d32..f194f8a 100644
    a b The Django open-source project  
    199199==============================
    200200
    201201    * **Community:**
    202       :doc:`How to get involved <internals/contributing>` |
     202      :doc:`How to get involved <internals/contributing/index>` |
    203203      :doc:`The release process <internals/release-process>` |
    204204      :doc:`Team of committers <internals/committers>` |
    205205      :doc:`The Django source code repository <internals/svn>`
    … … The Django open-source project  
    208208      :doc:`Overview <misc/design-philosophies>`
    209209
    210210    * **Documentation:**
    211       :doc:`About this documentation <internals/documentation>`
     211      :doc:`About this documentation <internals/contributing/writing-documentation>`
    212212
    213213    * **Third-party distributions:**
    214214      :doc:`Overview <misc/distributions>`

  • docs/internals/committers.txt 

    diff --git a/docs/internals/committers.txt b/docs/internals/committers.txt
index ab10215..7b727d6 100644
    a b Current developers  
    5858
    5959Currently, Django is led by a team of volunteers from around the globe.
    6060
     61.. _django-bdfls:
     62
    6163BDFLs
    6264-----
    6365

  • deleted file docs/internals/contributing.txt 

    diff --git a/docs/internals/contributing.txt b/docs/internals/contributing.txt
deleted file mode 100644
index 4e2bad9..0000000
    + -  
    1 ======================
    2 Contributing to Django
    3 ======================
    4 
    5 If you think working *with* Django is fun, wait until you start working *on*
    6 it. We're passionate about helping Django users make the jump to contributing
    7 members of the community, so there are many ways you can help Django's
    8 development:
    9 
    10     * Blog about Django. We syndicate all the Django blogs we know about on
    11       the `community page`_; contact jacob@jacobian.org if you've got a blog
    12       you'd like to see on that page.
    13 
    14     * Report bugs and request features in our `ticket tracker`_. Please read
    15       `Reporting bugs`_, below, for the details on how we like our bug reports
    16       served up.
    17 
    18     * Submit patches for new and/or fixed behavior. Please read `Submitting
    19       patches`_, below, for details on how to submit a patch. If you're looking
    20       for an easy way to start contributing to Django have a look at the
    21       `easy-pickings`_ tickets.
    22 
    23     * Join the `django-developers`_ mailing list and share your ideas for how
    24       to improve Django. We're always open to suggestions, although we're
    25       likely to be skeptical of large-scale suggestions without some code to
    26       back it up.
    27 
    28     * Triage patches that have been submitted by other users. Please read
    29       `Ticket triage`_ below, for details on the triage process.
    30 
    31 That's all you need to know if you'd like to join the Django development
    32 community. The rest of this document describes the details of how our community
    33 works and how it handles bugs, mailing lists, and all the other minutiae of
    34 Django development.
    35 
    36 .. seealso::
    37 
    38     This document contains specific details for contributing to
    39     Django. However, many new contributors find this guide confusing
    40     or intimidating at first. For a simpler introduction
    41     to becoming a contributor please see the :doc:`/howto/contribute` guide.
    42 
    43 .. _reporting-bugs:
    44 
    45 Reporting bugs
    46 ==============
    47 
    48 Well-written bug reports are *incredibly* helpful. However, there's a certain
    49 amount of overhead involved in working with any bug tracking system so your
    50 help in keeping our ticket tracker as useful as possible is appreciated. In
    51 particular:
    52 
    53     * **Do** read the :doc:`FAQ </faq/index>` to see if your issue might
    54       be a well-known question.
    55 
    56     * **Do** `search the tracker`_ to see if your issue has already been filed.
    57 
    58     * **Do** ask on `django-users`_ *first* if you're not sure if what you're
    59       seeing is a bug.
    60 
    61     * **Do** write complete, reproducible, specific bug reports. Include as
    62       much information as you possibly can, complete with code snippets, test
    63       cases, etc. This means including a clear, concise description of the
    64       problem, and a clear set of instructions for replicating the problem.
    65       A minimal example that illustrates the bug in a nice small test case
    66       is the best possible bug report.
    67 
    68     * **Don't** use the ticket system to ask support questions. Use the
    69       `django-users`_ list, or the `#django`_ IRC channel for that.
    70 
    71     * **Don't** use the ticket system to make large-scale feature requests.
    72       We like to discuss any big changes to Django's core on the
    73       `django-developers`_ list before actually working on them.
    74 
    75     * **Don't** reopen issues that have been marked "wontfix". This mark
    76       means that the decision has been made that we can't or won't fix
    77       this particular issue. If you're not sure why, please ask
    78       on `django-developers`_.
    79 
    80     * **Don't** use the ticket tracker for lengthy discussions, because they're
    81       likely to get lost. If a particular ticket is controversial, please move
    82       discussion to `django-developers`_.
    83 
    84     * **Don't** post to django-developers just to announce that you have filed
    85       a bug report. All the tickets are mailed to another list
    86       (`django-updates`_), which is tracked by developers and interested
    87       community members; we see them as they are filed.
    88 
    89 .. _django-updates: http://groups.google.com/group/django-updates
    90 
    91 .. _reporting-security-issues:
    92 
    93 Reporting security issues
    94 =========================
    95 
    96 Report security issues to security@djangoproject.com. This is a private list
    97 only open to long-time, highly trusted Django developers, and its archives are
    98 not publicly readable.
    99 
    100 In the event of a confirmed vulnerability in Django itself, we will take the
    101 following actions:
    102 
    103     * Acknowledge to the reporter that we've received the report and that a
    104       fix is forthcoming. We'll give a rough timeline and ask the reporter
    105       to keep the issue confidential until we announce it.
    106 
    107     * Focus on developing a fix as quickly as possible and produce patches
    108       against the current and two previous releases.
    109 
    110     * Determine a go-public date for announcing the vulnerability and the fix.
    111       To try to mitigate a possible "arms race" between those applying the
    112       patch and those trying to exploit the hole, we will not announce
    113       security problems immediately.
    114 
    115     * Pre-notify third-party distributors of Django ("vendors"). We will send
    116       these vendor notifications through private email which will include
    117       documentation of the vulnerability, links to the relevant patch(es), and a
    118       request to keep the vulnerability confidential until the official
    119       go-public date.
    120 
    121     * Publicly announce the vulnerability and the fix on the pre-determined
    122       go-public date. This will probably mean a new release of Django, but
    123       in some cases it may simply be patches against current releases.
    124 
    125 Submitting patches
    126 ==================
    127 
    128 We're always grateful for patches to Django's code. Indeed, bug reports
    129 with associated patches will get fixed *far* more quickly than those
    130 without patches.
    131 
    132 "Claiming" tickets
    133 ------------------
    134 
    135 In an open-source project with hundreds of contributors around the world, it's
    136 important to manage communication efficiently so that work doesn't get
    137 duplicated and contributors can be as effective as possible. Hence, our policy
    138 is for contributors to "claim" tickets in order to let other developers know
    139 that a particular bug or feature is being worked on.
    140 
    141 If you have identified a contribution you want to make and you're capable of
    142 fixing it (as measured by your coding ability, knowledge of Django internals
    143 and time availability), claim it by following these steps:
    144 
    145     * `Create an account`_ to use in our ticket system.
    146 
    147     * If a ticket for this issue doesn't exist yet, create one in our
    148       `ticket tracker`_.
    149 
    150     * If a ticket for this issue already exists, make sure nobody else has
    151       claimed it. To do this, look at the "Assigned to" section of the ticket.
    152       If it's assigned to "nobody," then it's available to be claimed.
    153       Otherwise, somebody else is working on this ticket, and you either find
    154       another bug/feature to work on, or contact the developer working on the
    155       ticket to offer your help.
    156 
    157     * Log into your account, if you haven't already, by clicking "Login" in the
    158       upper right of the ticket page.
    159 
    160     * Claim the ticket by clicking the radio button next to "Accept ticket"
    161       near the bottom of the page, then clicking "Submit changes."
    162 
    163 If you have an account but have forgotten your password, you can reset it
    164 using the `password reset page`_.
    165 
    166 .. _Create an account: http://www.djangoproject.com/accounts/register/
    167 .. _password reset page: http://www.djangoproject.com/accounts/password/reset/
    168 
    169 Ticket claimers' responsibility
    170 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    171 
    172 Once you've claimed a ticket, you have a responsibility to work on that ticket
    173 in a reasonably timely fashion. If you don't have time to work on it, either
    174 unclaim it or don't claim it in the first place!
    175 
    176 If there's no sign of progress on a particular claimed ticket for a week or
    177 two, another developer may ask you to relinquish the ticket claim so that it's
    178 no longer monopolized and somebody else can claim it.
    179 
    180 If you've claimed a ticket and it's taking a long time (days or weeks) to code,
    181 keep everybody updated by posting comments on the ticket. If you don't provide
    182 regular updates, and you don't respond to a request for a progress report,
    183 your claim on the ticket may be revoked. As always, more communication is
    184 better than less communication!
    185 
    186 Which tickets should be claimed?
    187 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    188 
    189 Of course, going through the steps of claiming tickets is overkill in some
    190 cases. In the case of small changes, such as typos in the documentation or
    191 small bugs that will only take a few minutes to fix, you don't need to jump
    192 through the hoops of claiming tickets. Just submit your patch and be done with
    193 it.
    194 
    195 Patch style
    196 -----------
    197 
    198     * Make sure your code matches our `coding style`_.
    199 
    200     * Submit patches in the format returned by the ``svn diff`` command.
    201       An exception is for code changes that are described more clearly in
    202       plain English than in code. Indentation is the most common example; it's
    203       hard to read patches when the only difference in code is that it's
    204       indented.
    205 
    206       Patches in ``git diff`` format are also acceptable.
    207 
    208     * When creating patches, always run ``svn diff`` from the top-level
    209       ``trunk`` directory -- i.e., the one that contains ``django``, ``docs``,
    210       ``tests``, ``AUTHORS``, etc. This makes it easy for other people to
    211       apply your patches.
    212 
    213     * Attach patches to a ticket in the `ticket tracker`_, using the "attach
    214       file" button. Please *don't* put the patch in the ticket description
    215       or comment unless it's a single line patch.
    216 
    217     * Name the patch file with a ``.diff`` extension; this will let the ticket
    218       tracker apply correct syntax highlighting, which is quite helpful.
    219 
    220     * Check the "Has patch" box on the ticket details. This will make it
    221       obvious that the ticket includes a patch, and it will add the ticket to
    222       the `list of tickets with patches`_.
    223 
    224     * The code required to fix a problem or add a feature is an essential part
    225       of a patch, but it is not the only part. A good patch should also include
    226       a regression test to validate the behavior that has been fixed
    227       (and prevent the problem from arising again).
    228 
    229     * If the code associated with a patch adds a new feature, or modifies
    230       behavior of an existing feature, the patch should also contain
    231       documentation.
    232 
    233 Non-trivial patches
    234 -------------------
    235 
    236 A "non-trivial" patch is one that is more than a simple bug fix. It's a patch
    237 that introduces Django functionality and makes some sort of design decision.
    238 
    239 If you provide a non-trivial patch, include evidence that alternatives have
    240 been discussed on `django-developers`_. If you're not sure whether your patch
    241 should be considered non-trivial, just ask.
    242 
    243 Ticket triage
    244 =============
    245 
    246 Unfortunately, not all bug reports in the `ticket tracker`_ provide all
    247 the `required details`_. A number of tickets have patches, but those patches
    248 don't meet all the requirements of a `good patch`_.
    249 
    250 One way to help out is to *triage* bugs that have been reported by other
    251 users. The core team--as well as many community members--work on this
    252 regularly, but more help is always appreciated.
    253 
    254 Most of the workflow is based around the concept of a ticket's "triage stage".
    255 This stage describes where in its lifetime a given ticket is at any time.
    256 Along with a handful of flags, this field easily tells us what and who each
    257 ticket is waiting on.
    258 
    259 Since a picture is worth a thousand words, let's start there:
    260 
    261 .. image:: _images/djangotickets.png
    262    :height: 451
    263    :width: 590
    264    :alt: Django's ticket workflow
    265 
    266 We've got two roles in this diagram:
    267 
    268     * Core developers: people with commit access who are responsible for
    269       making the big decisions, writing large portions of the code and
    270       integrating the contributions of the community.
    271 
    272     * Ticket triagers: anyone in the Django community who chooses to
    273       become involved in Django's development process. Our Trac installation
    274       is :ref:`intentionally left open to the public
    275       <the-spirit-of-contributing>`, and anyone can triage tickets.
    276       Django is a community project, and we encourage `triage by the
    277       community`_.
    278 
    279 Triage stages
    280 -------------
    281 
    282 Second, note the five triage stages:
    283 
    284     1. A ticket starts as **Unreviewed**, meaning that nobody has examined
    285        the ticket.
    286 
    287     2. **Design decision needed** means "this concept requires a design
    288        decision," which should be discussed either in the ticket comments or on
    289        `django-developers`_. The "Design decision needed" step will generally
    290        only be used for feature requests. It can also be used for issues
    291        that *might* be bugs, depending on opinion or interpretation. Obvious
    292        bugs (such as crashes, incorrect query results, or non-compliance with a
    293        standard) skip this step and move straight to "Accepted".
    294 
    295     3. Once a ticket is ruled to be approved for fixing, it's moved into the
    296        **Accepted** stage. This stage is where all the real work gets done.
    297 
    298     4. In some cases, a ticket might get moved to the **Someday/Maybe** state.
    299        This means the ticket is an enhancement request that we might consider
    300        adding to the framework if an excellent patch is submitted. These
    301        tickets are not a high priority.
    302 
    303     5. If a ticket has an associated patch (see below), it will be reviewed
    304        by the community. If the patch is complete, it'll be marked as **Ready
    305        for checkin** so that a core developer knows to review and commit the
    306        patch.
    307 
    308 The second part of this workflow involves a set of flags the describe what the
    309 ticket has or needs in order to be "ready for checkin":
    310 
    311     "Has patch"
    312         This means the ticket has an associated patch_. These will be
    313         reviewed to see if the patch is "good".
    314 
    315     "Needs documentation"
    316         This flag is used for tickets with patches that need associated
    317         documentation. Complete documentation of features is a prerequisite
    318         before we can check them into the codebase.
    319 
    320     "Needs tests"
    321         This flags the patch as needing associated unit tests. Again, this is a
    322         required part of a valid patch.
    323 
    324     "Patch needs improvement"
    325         This flag means that although the ticket *has* a patch, it's not quite
    326         ready for checkin. This could mean the patch no longer applies
    327         cleanly, there is a flaw in the implementation, or that the code
    328         doesn't meet our standards.
    329 
    330 .. seealso::
    331 
    332     The :ref:`contributing howto guide <triage-stages-explained>` has a detailed
    333     explanation of each of the triage stages and how the triage process works in
    334     Trac.
    335 
    336 .. _ticket-resolutions:
    337 
    338 Ticket Resolutions
    339 ------------------
    340 
    341 A ticket can be resolved in a number of ways:
    342 
    343     "fixed"
    344         Used by the core developers once a patch has been rolled into
    345         Django and the issue is fixed.
    346 
    347     "invalid"
    348         Used if the ticket is found to be incorrect. This means that the
    349         issue in the ticket is actually the result of a user error, or
    350         describes a problem with something other than Django, or isn't
    351         a bug report or feature request at all (for example, some new users
    352         submit support queries as tickets).
    353 
    354     "wontfix"
    355         Used when a core developer decides that this request is not
    356         appropriate for consideration in Django. This is usually chosen after
    357         discussion in the ``django-developers`` mailing list. Feel free to
    358         start or join in discussions of "wontfix" tickets on the mailing list,
    359         but please do not reopen tickets closed as "wontfix" by core
    360         developers.
    361 
    362     "duplicate"
    363         Used when another ticket covers the same issue. By closing duplicate
    364         tickets, we keep all the discussion in one place, which helps everyone.
    365 
    366     "worksforme"
    367         Used when the ticket doesn't contain enough detail to replicate
    368         the original bug.
    369 
    370     "needsinfo"
    371         Used when the ticket does not contain enough information to replicate
    372         the reported issue but is potentially still valid. The ticket
    373         should be reopened when more information is supplied.
    374 
    375 If you believe that the ticket was closed in error -- because you're
    376 still having the issue, or it's popped up somewhere else, or the triagers have
    377 made a mistake -- please reopen the ticket and provide further information.
    378 Please do not reopen tickets that have been marked as "wontfix" by core
    379 developers.
    380 
    381 .. seealso::
    382 
    383     For more information on what to do when closing a ticket, please see the
    384     :ref:`contributing howto guide <closing-tickets>`.
    385 
    386 .. _required details: `Reporting bugs`_
    387 .. _good patch: `Patch style`_
    388 .. _triage by the community: `Triage by the general community`_
    389 .. _patch: `Submitting patches`_
    390 
    391 Triage by the general community
    392 -------------------------------
    393 
    394 Although the core developers make the big decisions in the ticket triage
    395 process, there's a lot that general community members can do to help the
    396 triage process. In particular, you can help out by:
    397 
    398     * Closing "Unreviewed" tickets as "invalid", "worksforme" or "duplicate."
    399 
    400     * Promoting "Unreviewed" tickets to "Design decision needed" if a design
    401       decision needs to be made, or "Accepted" in case of obvious bugs.
    402 
    403     * Correcting the "Needs tests", "Needs documentation", or "Has patch"
    404       flags for tickets where they are incorrectly set.
    405 
    406     * Adding the `easy-pickings`_ keyword to tickets that are small and
    407       relatively straightforward.
    408 
    409     * Checking that old tickets are still valid. If a ticket hasn't seen
    410       any activity in a long time, it's possible that the problem has been
    411       fixed but the ticket hasn't yet been closed.
    412 
    413     * Contacting the owners of tickets that have been claimed but have not
    414       seen any recent activity. If the owner doesn't respond after a week
    415       or so, remove the owner's claim on the ticket.
    416 
    417     * Identifying trends and themes in the tickets. If there a lot of bug
    418       reports about a particular part of Django, it may indicate we should
    419       consider refactoring that part of the code. If a trend is emerging,
    420       you should raise it for discussion (referencing the relevant tickets)
    421       on `django-developers`_.
    422 
    423 However, we do ask the following of all general community members working in
    424 the ticket database:
    425 
    426     * Please **don't** close tickets as "wontfix." The core developers will
    427       make the final determination of the fate of a ticket, usually after
    428       consultation with the community.
    429 
    430     * Please **don't** promote your own tickets to "Ready for checkin". You
    431       may mark other people's tickets which you've reviewed as "Ready for
    432       checkin", but you should get at minimum one other community member to
    433       review a patch that you submit.
    434 
    435     * Please **don't** reverse a decision that has been made by a core
    436       developer. If you disagree with a decision that has been made,
    437       please post a message to `django-developers`_.
    438 
    439     * If you're unsure if you should be making a change, don't make the change
    440       but instead leave a comment with your concerns on the ticket, or
    441       post a message to `django-developers`_. It's okay to be unsure, but
    442       your input is still valuable.
    443 
    444 .. _contributing-translations:
    445 
    446 Submitting and maintaining translations
    447 =======================================
    448 
    449 Various parts of Django, such as the admin site and validation error messages,
    450 are internationalized. This means they display different text depending on a
    451 user's language setting. For this, Django uses the same internationalization
    452 infrastructure available to Django applications described in the
    453 :doc:`i18n documentation</topics/i18n/index>`.
    454 
    455 These translations are contributed by Django users worldwide. If you find an
    456 incorrect translation or want to discuss specific translations, go to the
    457 `translation team`_ page for that language. If you would like to help out
    458 with translating or add a language that isn't yet translated, here's what
    459 to do:
    460 
    461     * Join the `Django i18n mailing list`_ and introduce yourself.
    462 
    463     * Make sure you read the notes about :ref:`specialties-of-django-i18n`.
    464 
    465     * Signup at `Transifex`_ and visit the `Django project page`_.
    466 
    467     * On the "`Translation Teams`_" page, choose the language team you want
    468       to work with, **or** -- in case the language team doesn't exist yet --
    469       request a new team by clicking on the "Request a new team" button
    470       and select the appropriate language.
    471 
    472     * Then, click the "Join this Team" button to become a member of this team.
    473       Every team has at least one coordinator who is responsible to review
    474       your membership request. You can of course also contact the team
    475       coordinator to clarify procedural problems and handle the actual
    476       translation process.
    477 
    478     * Once you are a member of a team choose the translation resource you
    479       want update on the team page. For example the "core" resource refers
    480       to the translation catalogue that contains all non-app translations.
    481       Each of the contrib apps also have a resource (prefixed with "contrib-").
    482 
    483       .. note::
    484          For more information about how to use Transifex, see the
    485          `Transifex Help`_
    486 
    487     * Optionally, review and update the ``conf/locale/<locale>/formats.py``
    488       file to describe the date, time and numbers formatting particularities
    489       of your locale. These files aren't covered by the use of Transifex and
    490       require a patch against the Django source tree, just as a code change
    491       would:
    492 
    493       * Create a diff against the current Subversion trunk.
    494 
    495       * Open a ticket in Django's ticket system, set its ``Component`` field
    496         to ``Translations``, and attach the patch to it. See
    497         :ref:`format-localization` for details.
    498 
    499 .. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
    500 .. _Transifex: http://www.transifex.net/
    501 .. _Django project page: http://www.transifex.net/projects/p/django/
    502 .. _translation teams: http://www.transifex.net/projects/p/django/teams/
    503 .. _translation team: http://www.transifex.net/projects/p/django/teams/
    504 .. _Transifex Help: http://help.transifex.net/
    505 
    506 Submitting javascript patches
    507 =============================
    508 
    509 .. versionadded:: 1.2
    510 
    511 Django's admin system leverages the jQuery framework to increase the
    512 capabilities of the admin interface. In conjunction, there is an emphasis on
    513 admin javascript performance and minimizing overall admin media file size.
    514 Serving compressed or "minified" versions of javascript files is considered
    515 best practice in this regard.
    516 
    517 To that end, patches for javascript files should include both the original
    518 code for future development (e.g. "foo.js"), and a compressed version for
    519 production use (e.g. "foo.min.js"). Any links to the file in the codebase
    520 should point to the compressed version.
    521 
    522 To simplify the process of providing optimized javascript code, Django
    523 includes a handy script which should be used to create a "minified" version.
    524 This script is located at ``/contrib/admin/media/js/compress.py``.
    525 
    526 Behind the scenes, ``compress.py`` is a front-end for Google's
    527 `Closure Compiler`_ which is written in Java. However, the Closure Compiler
    528 library is not bundled with Django directly, so those wishing to contribute
    529 complete javascript patches will need to download and install the library
    530 independently.
    531 
    532 The Closure Compiler library requires Java version 6 or higher (Java 1.6 or
    533 higher on Mac OS X). Note that Mac OS X 10.5 and earlier did not ship with Java
    534 1.6 by default, so it may be necessary to upgrade your Java installation before
    535 the tool will be functional. Also note that even after upgrading Java, the
    536 default `/usr/bin/java` command may remain linked to the previous Java
    537 binary, so relinking that command may be necessary as well.
    538 
    539 Please don't forget to run ``compress.py`` and include the ``diff`` of the
    540 minified scripts when submitting patches for Django's javascript.
    541 
    542 .. _Closure Compiler: http://code.google.com/closure/compiler/
    543 
    544 Django conventions
    545 ==================
    546 
    547 Various Django-specific code issues are detailed in this section.
    548 
    549 Use of ``django.conf.settings``
    550 -------------------------------
    551 
    552 Modules should not in general use settings stored in ``django.conf.settings``
    553 at the top level (i.e. evaluated when the module is imported). The explanation
    554 for this is as follows:
    555 
    556 Manual configuration of settings (i.e. not relying on the
    557 ``DJANGO_SETTINGS_MODULE`` environment variable) is allowed and possible as
    558 follows::
    559 
    560     from django.conf import settings
    561 
    562     settings.configure({}, SOME_SETTING='foo')
    563 
    564 However, if any setting is accessed before the ``settings.configure`` line,
    565 this will not work. (Internally, ``settings`` is a ``LazyObject`` which
    566 configures itself automatically when the settings are accessed if it has not
    567 already been configured).
    568 
    569 So, if there is a module containing some code as follows::
    570 
    571     from django.conf import settings
    572     from django.core.urlresolvers import get_callable
    573 
    574     default_foo_view = get_callable(settings.FOO_VIEW)
    575 
    576 ...then importing this module will cause the settings object to be configured.
    577 That means that the ability for third parties to import the module at the top
    578 level is incompatible with the ability to configure the settings object
    579 manually, or makes it very difficult in some circumstances.
    580 
    581 Instead of the above code, a level of laziness or indirection must be used,
    582 such as `django.utils.functional.LazyObject``, ``django.utils.functional.lazy``
    583 or ``lambda``.
    584 
    585 Coding style
    586 ============
    587 
    588 Please follow these coding standards when writing code for inclusion in Django:
    589 
    590     * Unless otherwise specified, follow :pep:`8`.
    591 
    592       You could use a tool like `pep8.py`_ to check for some problems in this
    593       area, but remember that PEP 8 is only a guide, so respect the style of
    594       the surrounding code as a primary goal.
    595 
    596     * Use four spaces for indentation.
    597 
    598     * Use underscores, not camelCase, for variable, function and method names
    599       (i.e. ``poll.get_unique_voters()``, not ``poll.getUniqueVoters``).
    600 
    601     * Use ``InitialCaps`` for class names (or for factory functions that
    602       return classes).
    603 
    604     * Mark all strings for internationalization; see the :doc:`i18n
    605       documentation </topics/i18n/index>` for details.
    606 
    607     * In docstrings, use "action words" such as::
    608 
    609           def foo():
    610               """
    611               Calculates something and returns the result.
    612               """
    613               pass
    614 
    615       Here's an example of what not to do::
    616 
    617           def foo():
    618               """
    619               Calculate something and return the result.
    620               """
    621               pass
    622 
    623     * Please don't put your name in the code you contribute. Our policy is to
    624       keep contributors' names in the ``AUTHORS`` file distributed with Django
    625       -- not scattered throughout the codebase itself. Feel free to include a
    626       change to the ``AUTHORS`` file in your patch if you make more than a
    627       single trivial change.
    628 
    629 Template style
    630 --------------
    631 
    632     * In Django template code, put one (and only one) space between the curly
    633       brackets and the tag contents.
    634 
    635       Do this:
    636 
    637       .. code-block:: html+django
    638 
    639           {{ foo }}
    640 
    641       Don't do this:
    642 
    643       .. code-block:: html+django
    644 
    645           {{foo}}
    646 
    647 View style
    648 ----------
    649 
    650     * In Django views, the first parameter in a view function should be called
    651       ``request``.
    652 
    653       Do this::
    654 
    655           def my_view(request, foo):
    656               # ...
    657 
    658       Don't do this::
    659 
    660           def my_view(req, foo):
    661               # ...
    662 
    663 Model style
    664 -----------
    665 
    666     * Field names should be all lowercase, using underscores instead of
    667       camelCase.
    668 
    669       Do this::
    670 
    671           class Person(models.Model):
    672               first_name = models.CharField(max_length=20)
    673               last_name = models.CharField(max_length=40)
    674 
    675       Don't do this::
    676 
    677           class Person(models.Model):
    678               FirstName = models.CharField(max_length=20)
    679               Last_Name = models.CharField(max_length=40)
    680 
    681     * The ``class Meta`` should appear *after* the fields are defined, with
    682       a single blank line separating the fields and the class definition.
    683 
    684       Do this::
    685 
    686           class Person(models.Model):
    687               first_name = models.CharField(max_length=20)
    688               last_name = models.CharField(max_length=40)
    689 
    690               class Meta:
    691                   verbose_name_plural = 'people'
    692 
    693       Don't do this::
    694 
    695           class Person(models.Model):
    696               first_name = models.CharField(max_length=20)
    697               last_name = models.CharField(max_length=40)
    698               class Meta:
    699                   verbose_name_plural = 'people'
    700 
    701       Don't do this, either::
    702 
    703           class Person(models.Model):
    704               class Meta:
    705                   verbose_name_plural = 'people'
    706 
    707               first_name = models.CharField(max_length=20)
    708               last_name = models.CharField(max_length=40)
    709 
    710     * The order of model inner classes and standard methods should be as
    711       follows (noting that these are not all required):
    712 
    713         * All database fields
    714         * Custom manager attributes
    715         * ``class Meta``
    716         * ``def __unicode__()``
    717         * ``def __str__()``
    718         * ``def save()``
    719         * ``def get_absolute_url()``
    720         * Any custom methods
    721 
    722     * If ``choices`` is defined for a given model field, define the choices as
    723       a tuple of tuples, with an all-uppercase name, either near the top of the
    724       model module or just above the model class. Example::
    725 
    726           GENDER_CHOICES = (
    727               ('M', 'Male'),
    728               ('F', 'Female'),
    729           )
    730 
    731 Documentation style
    732 ===================
    733 
    734 We place a high importance on consistency and readability of documentation.
    735 (After all, Django was created in a journalism environment!)
    736 
    737 How to document new features
    738 ----------------------------
    739 
    740 We treat our documentation like we treat our code: we aim to improve it as
    741 often as possible. This section explains how writers can craft their
    742 documentation changes in the most useful and least error-prone ways.
    743 
    744 Documentation changes come in two forms:
    745 
    746     * General improvements -- Typo corrections, error fixes and better
    747       explanations through clearer writing and more examples.
    748 
    749     * New features -- Documentation of features that have been added to the
    750       framework since the last release.
    751 
    752 Our policy is:
    753 
    754     **All documentation of new features should be written in a way that clearly
    755     designates the features are only available in the Django development
    756     version. Assume documentation readers are using the latest release, not the
    757     development version.**
    758 
    759 Our preferred way for marking new features is by prefacing the features'
    760 documentation with: ".. versionadded:: X.Y", followed by an optional one line
    761 comment and a mandatory blank line.
    762 
    763 General improvements, or other changes to the APIs that should be emphasized
    764 should use the ".. versionchanged:: X.Y" directive (with the same format as the
    765 ``versionadded`` mentioned above.
    766 
    767 There's a full page of information about the :doc:`Django documentation
    768 system </internals/documentation>` that you should read prior to working on the
    769 documentation.
    770 
    771 Guidelines for reST files
    772 -------------------------
    773 
    774 These guidelines regulate the format of our reST documentation:
    775 
    776     * In section titles, capitalize only initial words and proper nouns.
    777 
    778     * Wrap the documentation at 80 characters wide, unless a code example
    779       is significantly less readable when split over two lines, or for another
    780       good reason.
    781 
    782 Commonly used terms
    783 -------------------
    784 
    785 Here are some style guidelines on commonly used terms throughout the
    786 documentation:
    787 
    788     * **Django** -- when referring to the framework, capitalize Django. It is
    789       lowercase only in Python code and in the djangoproject.com logo.
    790 
    791     * **email** -- no hyphen.
    792 
    793     * **MySQL**
    794 
    795     * **PostgreSQL**
    796 
    797     * **Python** -- when referring to the language, capitalize Python.
    798 
    799     * **realize**, **customize**, **initialize**, etc. -- use the American
    800       "ize" suffix, not "ise."
    801 
    802     * **SQLite**
    803 
    804     * **subclass** -- it's a single word without a hyphen, both as a verb
    805       ("subclass that model") and as a noun ("create a subclass").
    806 
    807     * **Web**, **World Wide Web**, **the Web** -- note Web is always
    808       capitalized when referring to the World Wide Web.
    809 
    810     * **Web site** -- use two words, with Web capitalized.
    811 
    812 Django-specific terminology
    813 ---------------------------
    814 
    815     * **model** -- it's not capitalized.
    816 
    817     * **template** -- it's not capitalized.
    818 
    819     * **URLconf** -- use three capitalized letters, with no space before
    820       "conf."
    821 
    822     * **view** -- it's not capitalized.
    823 
    824 Committing code
    825 ===============
    826 
    827 Please follow these guidelines when committing code to Django's Subversion
    828 repository:
    829 
    830     * For any medium-to-big changes, where "medium-to-big" is according to your
    831       judgment, please bring things up on the `django-developers`_ mailing list
    832       before making the change.
    833 
    834       If you bring something up on `django-developers`_ and nobody responds,
    835       please don't take that to mean your idea is great and should be
    836       implemented immediately because nobody contested it. Django's lead
    837       developers don't have a lot of time to read mailing-list discussions
    838       immediately, so you may have to wait a couple of days before getting a
    839       response.
    840 
    841     * Write detailed commit messages in the past tense, not present tense.
    842 
    843           * Good: "Fixed Unicode bug in RSS API."
    844           * Bad: "Fixes Unicode bug in RSS API."
    845           * Bad: "Fixing Unicode bug in RSS API."
    846 
    847     * For commits to a branch, prefix the commit message with the branch name.
    848       For example: "magic-removal: Added support for mind reading."
    849 
    850     * Limit commits to the most granular change that makes sense. This means,
    851       use frequent small commits rather than infrequent large commits. For
    852       example, if implementing feature X requires a small change to library Y,
    853       first commit the change to library Y, then commit feature X in a separate
    854       commit. This goes a *long way* in helping all core Django developers
    855       follow your changes.
    856 
    857     * Separate bug fixes from feature changes.
    858 
    859       Bug fixes need to be added to the current bugfix branch (e.g. the
    860       ``1.0.X`` branch) as well as the current trunk.
    861 
    862     * If your commit closes a ticket in the Django `ticket tracker`_, begin
    863       your commit message with the text "Fixed #abc", where "abc" is the number
    864       of the ticket your commit fixes. Example: "Fixed #123 -- Added support
    865       for foo". We've rigged Subversion and Trac so that any commit message
    866       in that format will automatically close the referenced ticket and post a
    867       comment to it with the full commit message.
    868 
    869       If your commit closes a ticket and is in a branch, use the branch name
    870       first, then the "Fixed #abc." For example:
    871       "magic-removal: Fixed #123 -- Added whizbang feature."
    872 
    873       For the curious: We're using a `Trac post-commit hook`_ for this.
    874 
    875       .. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook
    876 
    877     * If your commit references a ticket in the Django `ticket tracker`_ but
    878       does *not* close the ticket, include the phrase "Refs #abc", where "abc"
    879       is the number of the ticket your commit references. We've rigged
    880       Subversion and Trac so that any commit message in that format will
    881       automatically post a comment to the appropriate ticket.
    882 
    883 Reverting commits
    884 -----------------
    885 
    886 Nobody's perfect; mistakes will be committed. When a mistaken commit is
    887 discovered, please follow these guidelines:
    888 
    889     * Try very hard to ensure that mistakes don't happen. Just because we
    890       have a reversion policy doesn't relax your responsibility to aim for
    891       the highest quality possible. Really: double-check your work before
    892       you commit it in the first place!
    893 
    894     * If possible, have the original author revert his/her own commit.
    895 
    896     * Don't revert another author's changes without permission from the
    897       original author.
    898 
    899     * If the original author can't be reached (within a reasonable amount
    900       of time -- a day or so) and the problem is severe -- crashing bug,
    901       major test failures, etc -- then ask for objections on django-dev
    902       then revert if there are none.
    903 
    904     * If the problem is small (a feature commit after feature freeze,
    905       say), wait it out.
    906 
    907     * If there's a disagreement between the committer and the
    908       reverter-to-be then try to work it out on the `django-developers`_
    909       mailing list. If an agreement can't be reached then it should
    910       be put to a vote.
    911 
    912     * If the commit introduced a confirmed, disclosed security
    913       vulnerability then the commit may be reverted immediately without
    914       permission from anyone.
    915 
    916     * The release branch maintainer may back out commits to the release
    917       branch without permission if the commit breaks the release branch.
    918 
    919 .. _unit-tests:
    920 
    921 Unit tests
    922 ==========
    923 
    924 Django comes with a test suite of its own, in the ``tests`` directory of the
    925 Django tarball. It's our policy to make sure all tests pass at all times.
    926 
    927 The tests cover:
    928 
    929     * Models and the database API (``tests/modeltests/``).
    930     * Everything else in core Django code (``tests/regressiontests``)
    931     * Contrib apps (``django/contrib/<contribapp>/tests``, see below)
    932 
    933 We appreciate any and all contributions to the test suite!
    934 
    935 The Django tests all use the testing infrastructure that ships with Django for
    936 testing applications. See :doc:`Testing Django applications </topics/testing>`
    937 for an explanation of how to write new tests.
    938 
    939 .. _running-unit-tests:
    940 
    941 Running the unit tests
    942 ----------------------
    943 
    944 Quickstart
    945 ~~~~~~~~~~
    946 
    947 Running the tests requires a Django settings module that defines the
    948 databases to use. To make it easy to get started. Django provides a
    949 sample settings module that uses the SQLite database. To run the tests
    950 with this sample ``settings`` module, ``cd`` into the Django
    951 ``tests/`` directory and run:
    952 
    953 .. code-block:: bash
    954 
    955     ./runtests.py --settings=test_sqlite
    956 
    957 If you get an ``ImportError: No module named django.contrib`` error,
    958 you need to add your install of Django to your ``PYTHONPATH``. For
    959 more details on how to do this, read `Pointing Python at the new
    960 Django version`_ below.
    961 
    962 Using another ``settings`` module
    963 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    964 
    965 The included settings module allows you to run the test suite using
    966 SQLite. If you want to test behavior using a different database (and
    967 if you're proposing patches for Django, it's a good idea to test
    968 across databases), you may need to define your own settings file.
    969 
    970 To run the tests with different settings, ``cd`` to the ``tests/`` directory
    971 and type:
    972 
    973 .. code-block:: bash
    974 
    975     ./runtests.py --settings=path.to.django.settings
    976 
    977 The :setting:`DATABASES` setting in this test settings module needs to define
    978 two databases:
    979 
    980     * A ``default`` database. This database should use the backend that
    981       you want to use for primary testing
    982 
    983     * A database with the alias ``other``. The ``other`` database is
    984       used to establish that queries can be directed to different
    985       databases. As a result, this database can use any backend you
    986       want. It doesn't need to use the same backend as the ``default``
    987       database (although it can use the same backend if you want to).
    988 
    989 If you're using a backend that isn't SQLite, you will need to provide other
    990 details for each database:
    991 
    992     * The :setting:`USER` option for each of your databases needs to
    993       specify an existing user account for the database.
    994 
    995     * The :setting:`PASSWORD` option needs to provide the password for
    996       the :setting:`USER` that has been specified.
    997 
    998     * The :setting:`NAME` option must be the name of an existing database to
    999       which the given user has permission to connect. The unit tests will not
    1000       touch this database; the test runner creates a new database whose name is
    1001       :setting:`NAME` prefixed with ``test_``, and this test database is
    1002       deleted when the tests are finished. This means your user account needs
    1003       permission to execute ``CREATE DATABASE``.
    1004 
    1005 You will also need to ensure that your database uses UTF-8 as the default
    1006 character set. If your database server doesn't use UTF-8 as a default charset,
    1007 you will need to include a value for ``TEST_CHARSET`` in the settings
    1008 dictionary for the applicable database.
    1009 
    1010 Running only some of the tests
    1011 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1012 
    1013 Django's entire test suite takes a while to run, and running every single test
    1014 could be redundant if, say, you just added a test to Django that you want to
    1015 run quickly without running everything else. You can run a subset of the unit
    1016 tests by appending the names of the test modules to ``runtests.py`` on the
    1017 command line.
    1018 
    1019 For example, if you'd like to run tests only for generic relations and
    1020 internationalization, type:
    1021 
    1022 .. code-block:: bash
    1023 
    1024     ./runtests.py --settings=path.to.settings generic_relations i18n
    1025 
    1026 How do you find out the names of individual tests? Look in ``tests/modeltests``
    1027 and ``tests/regressiontests`` -- each directory name there is the name of a
    1028 test.
    1029 
    1030 If you just want to run a particular class of tests, you can specify a list of
    1031 paths to individual test classes. For example, to run the ``TranslationTests``
    1032 of the ``i18n`` module, type:
    1033 
    1034 .. code-block:: bash
    1035 
    1036     ./runtests.py --settings=path.to.settings i18n.TranslationTests
    1037 
    1038 Going beyond that, you can specify an individual test method like this:
    1039 
    1040 .. code-block:: bash
    1041 
    1042     ./runtests.py --settings=path.to.settings i18n.TranslationTests.test_lazy_objects
    1043 
    1044 Running all the tests
    1045 ~~~~~~~~~~~~~~~~~~~~~
    1046 
    1047 If you want to run the full suite of tests, you'll need to install a number of
    1048 dependencies:
    1049 
    1050     *  PyYAML_
    1051     *  Markdown_
    1052     *  Textile_
    1053     *  Docutils_
    1054     *  setuptools_
    1055     *  memcached_, plus a :ref:`supported Python binding <memcached>`
    1056     *  gettext_ (:ref:`gettext_on_windows`)
    1057 
    1058 If you want to test the memcached cache backend, you'll also need to define
    1059 a :setting:`CACHES` setting that points at your memcached instance.
    1060 
    1061 Each of these dependencies is optional. If you're missing any of them, the
    1062 associated tests will be skipped.
    1063 
    1064 .. _PyYAML: http://pyyaml.org/wiki/PyYAML
    1065 .. _Markdown: http://pypi.python.org/pypi/Markdown/1.7
    1066 .. _Textile: http://pypi.python.org/pypi/textile
    1067 .. _docutils: http://pypi.python.org/pypi/docutils/0.4
    1068 .. _setuptools: http://pypi.python.org/pypi/setuptools/
    1069 .. _memcached: http://www.danga.com/memcached/
    1070 .. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
    1071 
    1072 Contrib apps
    1073 ------------
    1074 
    1075 Tests for apps in ``django/contrib/`` go in their respective directories under
    1076 ``django/contrib/``, in a ``tests.py`` file. (You can split the tests over
    1077 multiple modules by using a ``tests`` directory in the normal Python way.)
    1078 
    1079 For the tests to be found, a ``models.py`` file must exist (it doesn't
    1080 have to have anything in it). If you have URLs that need to be
    1081 mapped, put them in ``tests/urls.py``.
    1082 
    1083 To run tests for just one contrib app (e.g. ``markup``), use the same
    1084 method as above::
    1085 
    1086     ./runtests.py --settings=settings markup
    1087 
    1088 Requesting features
    1089 ===================
    1090 
    1091 We're always trying to make Django better, and your feature requests are a key
    1092 part of that. Here are some tips on how to make a request most effectively:
    1093 
    1094     * Request the feature on `django-developers`_, not in the ticket tracker.
    1095       It'll get read more closely if it's on the mailing list.
    1096 
    1097     * Describe clearly and concisely what the missing feature is and how you'd
    1098       like to see it implemented. Include example code (non-functional is OK)
    1099       if possible.
    1100 
    1101     * Explain *why* you'd like the feature. In some cases this is obvious, but
    1102       since Django is designed to help real developers get real work done,
    1103       you'll need to explain it, if it isn't obvious why the feature would be
    1104       useful.
    1105 
    1106 As with most open-source projects, code talks. If you are willing to write the
    1107 code for the feature yourself or if (even better) you've already written it,
    1108 it's much more likely to be accepted. If it's a large feature that might need
    1109 multiple developers, we're always happy to give you an experimental branch in
    1110 our repository; see below.
    1111 
    1112 Branch policy
    1113 =============
    1114 
    1115 In general, the trunk must be kept stable. People should be able to run
    1116 production sites against the trunk at any time. Additionally, commits to trunk
    1117 ought to be as atomic as possible -- smaller changes are better. Thus, large
    1118 feature changes -- that is, changes too large to be encapsulated in a single
    1119 patch, or changes that need multiple eyes on them -- must happen on dedicated
    1120 branches.
    1121 
    1122 This means that if you want to work on a large feature -- anything that would
    1123 take more than a single patch, or requires large-scale refactoring -- you need
    1124 to do it on a feature branch. Our development process recognizes two options
    1125 for feature branches:
    1126 
    1127     1. Feature branches using a distributed revision control system like
    1128        Git_, Mercurial_, Bazaar_, etc.
    1129 
    1130        If you're familiar with one of these tools, this is probably your best
    1131        option since it doesn't require any support or buy-in from the Django
    1132        core developers.
    1133 
    1134        However, do keep in mind that Django will continue to use Subversion for
    1135        the foreseeable future, and this will naturally limit the recognition of
    1136        your branch. Further, if your branch becomes eligible for merging to
    1137        trunk you'll need to find a core developer familiar with your DVCS of
    1138        choice who'll actually perform the merge.
    1139 
    1140        If you do decided to start a distributed branch of Django and choose to
    1141        make it public, please add the branch to the `Django branches`_ wiki
    1142        page.
    1143 
    1144     2. Feature branches using SVN have a higher bar. If you want a branch
    1145        in SVN itself, you'll need a "mentor" among the :doc:`core committers
    1146        </internals/committers>`. This person is responsible for actually
    1147        creating the branch, monitoring your process (see below), and
    1148        ultimately merging the branch into trunk.
    1149 
    1150        If you want a feature branch in SVN, you'll need to ask in
    1151        `django-developers`_ for a mentor.
    1152 
    1153 .. _git: http://git-scm.com/
    1154 .. _mercurial: http://mercurial.selenic.com/
    1155 .. _bazaar: http://bazaar.canonical.com/
    1156 .. _django branches: http://code.djangoproject.com/wiki/DjangoBranches
    1157 
    1158 Branch rules
    1159 ------------
    1160 
    1161 We've got a few rules for branches born out of experience with what makes a
    1162 successful Django branch.
    1163 
    1164 DVCS branches are obviously not under central control, so we have no way of
    1165 enforcing these rules. However, if you're using a DVCS, following these rules
    1166 will give you the best chance of having a successful branch (read: merged back
    1167 to trunk).
    1168 
    1169 Developers with branches in SVN, however, **must** follow these rules. The
    1170 branch mentor will keep on eye on the branch and **will delete it** if these
    1171 rules are broken.
    1172 
    1173     * Only branch entire copies of the Django tree, even if work is only
    1174       happening on part of that tree. This makes it painless to switch to a
    1175       branch.
    1176 
    1177     * Merge changes from trunk no less than once a week, and preferably every
    1178       couple-three days.
    1179 
    1180       In our experience, doing regular trunk merges is often the difference
    1181       between a successful branch and one that fizzles and dies.
    1182 
    1183       If you're working on an SVN branch, you should be using `svnmerge.py`_
    1184       to track merges from trunk.
    1185 
    1186     * Keep tests passing and documentation up-to-date. As with patches,
    1187       we'll only merge a branch that comes with tests and documentation.
    1188 
    1189 .. _svnmerge.py: http://www.orcaware.com/svn/wiki/Svnmerge.py
    1190 
    1191 Once the branch is stable and ready to be merged into the trunk, alert
    1192 `django-developers`_.
    1193 
    1194 After a branch has been merged, it should be considered "dead"; write access to
    1195 it will be disabled, and old branches will be periodically "trimmed." To keep
    1196 our SVN wrangling to a minimum, we won't be merging from a given branch into
    1197 the trunk more than once.
    1198 
    1199 Using branches
    1200 --------------
    1201 
    1202 To use a branch, you'll need to do two things:
    1203 
    1204     * Get the branch's code through Subversion.
    1205 
    1206     * Point your Python ``site-packages`` directory at the branch's version of
    1207       the ``django`` package rather than the version you already have
    1208       installed.
    1209 
    1210 Getting the code from Subversion
    1211 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1212 
    1213 To get the latest version of a branch's code, check it out using Subversion:
    1214 
    1215 .. code-block:: bash
    1216 
    1217     svn co http://code.djangoproject.com/svn/django/branches/<branch>/
    1218 
    1219 ...where ``<branch>`` is the branch's name. See the `list of branch names`_.
    1220 
    1221 Alternatively, you can automatically convert an existing directory of the
    1222 Django source code as long as you've checked it out via Subversion. To do the
    1223 conversion, execute this command from within your ``django`` directory:
    1224 
    1225 .. code-block:: bash
    1226 
    1227     svn switch http://code.djangoproject.com/svn/django/branches/<branch>/
    1228 
    1229 The advantage of using ``svn switch`` instead of ``svn co`` is that the
    1230 ``switch`` command retains any changes you might have made to your local copy
    1231 of the code. It attempts to merge those changes into the "switched" code. The
    1232 disadvantage is that it may cause conflicts with your local changes if the
    1233 "switched" code has altered the same lines of code.
    1234 
    1235 (Note that if you use ``svn switch``, you don't need to point Python at the new
    1236 version, as explained in the next section.)
    1237 
    1238 .. _list of branch names: http://code.djangoproject.com/browser/django/branches
    1239 
    1240 Pointing Python at the new Django version
    1241 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1242 
    1243 Once you've retrieved the branch's code, you'll need to change your Python
    1244 ``site-packages`` directory so that it points to the branch version of the
    1245 ``django`` directory. (The ``site-packages`` directory is somewhere such as
    1246 ``/usr/lib/python2.4/site-packages`` or
    1247 ``/usr/local/lib/python2.4/site-packages`` or ``C:\Python\site-packages``.)
    1248 
    1249 The simplest way to do this is by renaming the old ``django`` directory to
    1250 ``django.OLD`` and moving the trunk version of the code into the directory
    1251 and calling it ``django``.
    1252 
    1253 Alternatively, you can use a symlink called ``django`` that points to the
    1254 location of the branch's ``django`` package. If you want to switch back, just
    1255 change the symlink to point to the old code.
    1256 
    1257 A third option is to use a `path file`_ (``<something>.pth``) which should
    1258 work on all systems (including Windows, which doesn't have symlinks
    1259 available). First, make sure there are no files, directories or symlinks named
    1260 ``django`` in your ``site-packages`` directory. Then create a text file named
    1261 ``django.pth`` and save it to your ``site-packages`` directory. That file
    1262 should contain a path to your copy of Django on a single line and optional
    1263 comments. Here is an example that points to multiple branches. Just uncomment
    1264 the line for the branch you want to use ('Trunk' in this example) and make
    1265 sure all other lines are commented::
    1266 
    1267     # Trunk is a svn checkout of:
    1268     #   http://code.djangoproject.com/svn/django/trunk/
    1269     #
    1270     /path/to/trunk
    1271 
    1272     # <branch> is a svn checkout of:
    1273     #   http://code.djangoproject.com/svn/django/branches/<branch>/
    1274     #
    1275     #/path/to/<branch>
    1276 
    1277     # On windows a path may look like this:
    1278     # C:/path/to/<branch>
    1279 
    1280 If you're using Django 0.95 or earlier and installed it using
    1281 ``python setup.py install``, you'll have a directory called something like
    1282 ``Django-0.95-py2.4.egg`` instead of ``django``. In this case, edit the file
    1283 ``setuptools.pth`` and remove the line that references the Django ``.egg``
    1284 file. Then copy the branch's version of the ``django`` directory into
    1285 ``site-packages``.
    1286 
    1287 .. _path file: http://docs.python.org/library/site.html
    1288 
    1289 How we make decisions
    1290 =====================
    1291 
    1292 Whenever possible, we strive for a rough consensus. To that end, we'll often
    1293 have informal votes on `django-developers`_ about a feature. In these votes we
    1294 follow the voting style invented by Apache and used on Python itself, where
    1295 votes are given as +1, +0, -0, or -1. Roughly translated, these votes mean:
    1296 
    1297     * +1: "I love the idea and I'm strongly committed to it."
    1298 
    1299     * +0: "Sounds OK to me."
    1300 
    1301     * -0: "I'm not thrilled, but I won't stand in the way."
    1302 
    1303     * -1: "I strongly disagree and would be very unhappy to see the idea turn
    1304       into reality."
    1305 
    1306 Although these votes on django-developers are informal, they'll be taken very
    1307 seriously. After a suitable voting period, if an obvious consensus arises
    1308 we'll follow the votes.
    1309 
    1310 However, consensus is not always possible. If consensus cannot be reached, or
    1311 if the discussion towards a consensus fizzles out without a concrete decision,
    1312 we use a more formal process.
    1313 
    1314 Any core committer (see below) may call for a formal vote using the same
    1315 voting mechanism above. A proposition will be considered carried by the core
    1316 team if:
    1317 
    1318     * There are three "+1" votes from members of the core team.
    1319 
    1320     * There is no "-1" vote from any member of the core team.
    1321 
    1322     * The BDFLs haven't stepped in and executed their positive or negative
    1323       veto.
    1324 
    1325 When calling for a vote, the caller should specify a deadline by which
    1326 votes must be received. One week is generally suggested as the minimum
    1327 amount of time.
    1328 
    1329 Since this process allows any core committer to veto a proposal, any "-1"
    1330 votes (or BDFL vetos) should be accompanied by an explanation that explains
    1331 what it would take to convert that "-1" into at least a "+0".
    1332 
    1333 Whenever possible, these formal votes should be announced and held in
    1334 public on the `django-developers`_ mailing list. However, overly sensitive
    1335 or contentious issues -- including, most notably, votes on new core
    1336 committers -- may be held in private.
    1337 
    1338 Commit access
    1339 =============
    1340 
    1341 Django has two types of committers:
    1342 
    1343 Core committers
    1344     These are people who have a long history of contributions to Django's
    1345     codebase, a solid track record of being polite and helpful on the
    1346     mailing lists, and a proven desire to dedicate serious time to Django's
    1347     development. The bar is high for full commit access.
    1348 
    1349 Partial committers
    1350     These are people who are "domain experts." They have direct check-in access
    1351     to the subsystems that fall under their jurisdiction, and they're given a
    1352     formal vote in questions that involve their subsystems. This type of access
    1353     is likely to be given to someone who contributes a large subframework to
    1354     Django and wants to continue to maintain it.
    1355 
    1356     Partial commit access is granted by the same process as full
    1357     committers. However, the bar is set lower; proven expertise in the area
    1358     in question is likely to be sufficient.
    1359 
    1360 Decisions on new committers will follow the process explained above in `how
    1361 we make decisions`_.
    1362 
    1363 To request commit access, please contact an existing committer privately.
    1364 Public requests for commit access are potential flame-war starters, and
    1365 will be ignored.
    1366 
    1367 .. _community page: http://www.djangoproject.com/community/
    1368 .. _ticket tracker: http://code.djangoproject.com/newticket
    1369 .. _django-developers: http://groups.google.com/group/django-developers
    1370 .. _search the tracker: http://code.djangoproject.com/search
    1371 .. _django-users: http://groups.google.com/group/django-users
    1372 .. _`#django`: irc://irc.freenode.net/django
    1373 .. _list of tickets with patches: http://code.djangoproject.com/query?status=new&status=assigned&status=reopened&has_patch=1&order=priority
    1374 .. _pep8.py: http://pypi.python.org/pypi/pep8/
    1375 .. _i18n branch: http://code.djangoproject.com/browser/django/branches/i18n
    1376 .. _`tags/releases`: http://code.djangoproject.com/browser/django/tags/releases
    1377 .. _`easy-pickings`: http://code.djangoproject.com/query?status=new&status=assigned&status=reopened&keywords=~easy-pickings&order=priority

  • new file docs/internals/contributing/bugs-and-features.txt 

    diff --git a/docs/internals/contributing/bugs-and-features.txt b/docs/internals/contributing/bugs-and-features.txt
new file mode 100644
index 0000000..ff4b4b1
    - +  
     1======================================
     2Reporting bugs and requesting features
     3======================================
     4
     5Before reporting a bug or requesting a new feature please consider these
     6general points:
     7
     8* Check that someone hasn't already filed the bug or feature request by
     9  `searching`_ or running `custom queries`_ in the ticket tracker.
     10
     11* Don't use the ticket system to ask support questions. Use the
     12  `django-users`_ list, or the `#django`_ IRC channel for that.
     13
     14* Don't reopen issues that have been marked "wontfix" by a core developer.
     15  This mark means that the decision has been made that we can't or won't fix
     16  this particular issue. If you're not sure why, please ask
     17  on `django-developers`_.
     18
     19* Don't use the ticket tracker for lengthy discussions, because they're
     20  likely to get lost. If a particular ticket is controversial, please move
     21  discussion to `django-developers`_.
     22
     23.. _reporting-bugs:
     24
     25Reporting bugs
     26--------------
     27
     28Well-written bug reports are *incredibly* helpful. However, there's a certain
     29amount of overhead involved in working with any bug tracking system so your
     30help in keeping our ticket tracker as useful as possible is appreciated. In
     31particular:
     32
     33    * **Do** read the :doc:`FAQ </faq/index>` to see if your issue might
     34      be a well-known question.
     35
     36    * **Do** ask on `django-users`_ *first* if you're not sure if what you're
     37      seeing is a bug.
     38
     39    * **Do** write complete, reproducible, specific bug reports. Include as
     40      much information as you possibly can, complete with code snippets, test
     41      cases, etc. This means including a clear, concise description of the
     42      problem, and a clear set of instructions for replicating the problem.
     43      A minimal example that illustrates the bug in a nice small test case
     44      is the best possible bug report.
     45
     46    * **Don't** post to django-developers just to announce that you have filed
     47      a bug report. All the tickets are mailed to another list
     48      (`django-updates`_), which is tracked by developers and interested
     49      community members; we see them as they are filed.
     50
     51To understand the lifecycle of your ticket once you have created it, refer to
     52:doc:`triaging-tickets`.
     53
     54.. _django-updates: http://groups.google.com/group/django-updates
     55
     56.. _reporting-security-issues:
     57
     58Reporting security issues
     59-------------------------
     60
     61.. Important::
     62
     63    Please report security issues **only** to security@djangoproject.com.
     64    This is a private list only open to long-time, highly trusted Django
     65    developers, and its archives are not publicly readable.
     66
     67In the event of a confirmed vulnerability in Django itself, we will take the
     68following actions:
     69
     70    * Acknowledge to the reporter that we've received the report and that a
     71      fix is forthcoming. We'll give a rough timeline and ask the reporter
     72      to keep the issue confidential until we announce it.
     73
     74    * Focus on developing a fix as quickly as possible and produce patches
     75      against the current and two previous releases.
     76
     77    * Determine a go-public date for announcing the vulnerability and the fix.
     78      To try to mitigate a possible "arms race" between those applying the
     79      patch and those trying to exploit the hole, we will not announce
     80      security problems immediately.
     81
     82    * Pre-notify third-party distributors of Django ("vendors"). We will send
     83      these vendor notifications through private email which will include
     84      documentation of the vulnerability, links to the relevant patch(es), and
     85      a request to keep the vulnerability confidential until the official
     86      go-public date.
     87
     88    * Publicly announce the vulnerability and the fix on the pre-determined
     89      go-public date. This will probably mean a new release of Django, but
     90      in some cases it may simply be patches against current releases.
     91
     92Requesting features
     93-------------------
     94
     95We're always trying to make Django better, and your feature requests are a key
     96part of that. Here are some tips on how to make a request most effectively:
     97
     98    * First request the feature on `django-developers`_, not in the ticket
     99      tracker. It'll get read more closely if it's on the mailing list.
     100
     101    * Describe clearly and concisely what the missing feature is and how you'd
     102      like to see it implemented. Include example code (non-functional is OK)
     103      if possible.
     104
     105    * Explain *why* you'd like the feature. In some cases this is obvious, but
     106      since Django is designed to help real developers get real work done,
     107      you'll need to explain it, if it isn't obvious why the feature would be
     108      useful.
     109
     110    * Don't use the ticket system to make large-scale feature requests.
     111      We like to discuss any big changes to Django's core on the
     112      `django-developers`_ list before actually working on them.
     113
     114As with most open-source projects, code talks. If you are willing to write the
     115code for the feature yourself or if (even better) you've already written it,
     116it's much more likely to be accepted. If it's a large feature that might need
     117multiple developers, we're always happy to give you an experimental branch in
     118our repository; see the :doc:`writing-code/branch-policy`.
     119
     120To understand the lifecycle of your ticket once you have created it, refer to
     121:doc:`triaging-tickets`.
     122
     123See also: :ref:`documenting-new-features`.
     124
     125.. _how-we-make-decisions:
     126
     127How we make decisions
     128---------------------
     129
     130Whenever possible, we strive for a rough consensus. To that end, we'll often
     131have informal votes on `django-developers`_ about a feature. In these votes we
     132follow the voting style invented by Apache and used on Python itself, where
     133votes are given as +1, +0, -0, or -1. Roughly translated, these votes mean:
     134
     135    * +1: "I love the idea and I'm strongly committed to it."
     136
     137    * +0: "Sounds OK to me."
     138
     139    * -0: "I'm not thrilled, but I won't stand in the way."
     140
     141    * -1: "I strongly disagree and would be very unhappy to see the idea turn
     142      into reality."
     143
     144Although these votes on django-developers are informal, they'll be taken very
     145seriously. After a suitable voting period, if an obvious consensus arises
     146we'll follow the votes.
     147
     148However, consensus is not always possible. If consensus cannot be reached, or
     149if the discussion towards a consensus fizzles out without a concrete decision,
     150we use a more formal process.
     151
     152Any :doc:`core committer</internals/committers>` may call for a formal vote
     153using the same voting mechanism above. A proposition will be considered carried
     154by the core team if:
     155
     156    * There are three "+1" votes from members of the core team.
     157
     158    * There is no "-1" vote from any member of the core team.
     159
     160    * The :ref:`BDFLs<django-bdfls>` haven't stepped in and executed their positive or
     161      negative veto.
     162
     163When calling for a vote, the caller should specify a deadline by which
     164votes must be received. One week is generally suggested as the minimum
     165amount of time.
     166
     167Since this process allows any core committer to veto a proposal, any "-1"
     168votes (or BDFL vetos) should be accompanied by an explanation that explains
     169what it would take to convert that "-1" into at least a "+0".
     170
     171Whenever possible, these formal votes should be announced and held in
     172public on the `django-developers`_ mailing list. However, overly sensitive
     173or contentious issues -- including, most notably, votes on new core
     174committers -- may be held in private.
     175
     176
     177.. _searching: http://code.djangoproject.com/search
     178.. _`custom queries`: https://code.djangoproject.com/query
     179.. _django-developers: http://groups.google.com/group/django-developers
     180.. _django-users: http://groups.google.com/group/django-users
     181.. _`#django`: irc://irc.freenode.net/django

  • new file docs/internals/contributing/committing-code.txt 

    diff --git a/docs/internals/contributing/committing-code.txt b/docs/internals/contributing/committing-code.txt
new file mode 100644
index 0000000..4f7f9e0
    - +  
     1===============
     2Committing code
     3===============
     4
     5This section is addressed to the :doc:`/internals/committers` and to anyone
     6interested in knowing how code gets committed into Django core.
     7
     8Commit access
     9-------------
     10
     11Django has two types of committers:
     12
     13Core committers
     14    These are people who have a long history of contributions to Django's
     15    codebase, a solid track record of being polite and helpful on the
     16    mailing lists, and a proven desire to dedicate serious time to Django's
     17    development. The bar is high for full commit access.
     18
     19Partial committers
     20    These are people who are "domain experts." They have direct check-in access
     21    to the subsystems that fall under their jurisdiction, and they're given a
     22    formal vote in questions that involve their subsystems. This type of access
     23    is likely to be given to someone who contributes a large subframework to
     24    Django and wants to continue to maintain it.
     25
     26    Partial commit access is granted by the same process as full
     27    committers. However, the bar is set lower; proven expertise in the area
     28    in question is likely to be sufficient.
     29
     30Decisions on new committers will follow the process explained in
     31:ref:`how-we-make-decisions`.
     32
     33To request commit access, please contact an existing committer privately.
     34Public requests for commit access are potential flame-war starters, and
     35will be ignored.
     36
     37Committing guidelines
     38---------------------
     39
     40Please follow these guidelines when committing code to Django's Subversion
     41repository:
     42
     43    * For any medium-to-big changes, where "medium-to-big" is according to your
     44      judgment, please bring things up on the `django-developers`_ mailing list
     45      before making the change.
     46
     47      If you bring something up on `django-developers`_ and nobody responds,
     48      please don't take that to mean your idea is great and should be
     49      implemented immediately because nobody contested it. Django's lead
     50      developers don't have a lot of time to read mailing-list discussions
     51      immediately, so you may have to wait a couple of days before getting a
     52      response.
     53
     54    * Write detailed commit messages in the past tense, not present tense.
     55
     56          * Good: "Fixed Unicode bug in RSS API."
     57          * Bad: "Fixes Unicode bug in RSS API."
     58          * Bad: "Fixing Unicode bug in RSS API."
     59
     60    * For commits to a branch, prefix the commit message with the branch name.
     61      For example: "magic-removal: Added support for mind reading."
     62
     63    * Limit commits to the most granular change that makes sense. This means,
     64      use frequent small commits rather than infrequent large commits. For
     65      example, if implementing feature X requires a small change to library Y,
     66      first commit the change to library Y, then commit feature X in a separate
     67      commit. This goes a *long way* in helping all core Django developers
     68      follow your changes.
     69
     70    * Separate bug fixes from feature changes.
     71
     72      Bug fixes need to be added to the current bugfix branch (e.g. the
     73      ``1.0.X`` branch) as well as the current trunk.
     74
     75    * If your commit closes a ticket in the Django `ticket tracker`_, begin
     76      your commit message with the text "Fixed #abc", where "abc" is the number
     77      of the ticket your commit fixes. Example: "Fixed #123 -- Added support
     78      for foo". We've rigged Subversion and Trac so that any commit message
     79      in that format will automatically close the referenced ticket and post a
     80      comment to it with the full commit message.
     81
     82      If your commit closes a ticket and is in a branch, use the branch name
     83      first, then the "Fixed #abc." For example:
     84      "magic-removal: Fixed #123 -- Added whizbang feature."
     85
     86      For the curious: We're using a `Trac post-commit hook`_ for this.
     87
     88      .. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook
     89
     90    * If your commit references a ticket in the Django `ticket tracker`_ but
     91      does *not* close the ticket, include the phrase "Refs #abc", where "abc"
     92      is the number of the ticket your commit references. We've rigged
     93      Subversion and Trac so that any commit message in that format will
     94      automatically post a comment to the appropriate ticket.
     95
     96Reverting commits
     97-----------------
     98
     99Nobody's perfect; mistakes will be committed. When a mistaken commit is
     100discovered, please follow these guidelines:
     101
     102    * Try very hard to ensure that mistakes don't happen. Just because we
     103      have a reversion policy doesn't relax your responsibility to aim for
     104      the highest quality possible. Really: double-check your work before
     105      you commit it in the first place!
     106
     107    * If possible, have the original author revert his/her own commit.
     108
     109    * Don't revert another author's changes without permission from the
     110      original author.
     111
     112    * If the original author can't be reached (within a reasonable amount
     113      of time -- a day or so) and the problem is severe -- crashing bug,
     114      major test failures, etc -- then ask for objections on django-dev
     115      then revert if there are none.
     116
     117    * If the problem is small (a feature commit after feature freeze,
     118      say), wait it out.
     119
     120    * If there's a disagreement between the committer and the
     121      reverter-to-be then try to work it out on the `django-developers`_
     122      mailing list. If an agreement can't be reached then it should
     123      be put to a vote.
     124
     125    * If the commit introduced a confirmed, disclosed security
     126      vulnerability then the commit may be reverted immediately without
     127      permission from anyone.
     128
     129    * The release branch maintainer may back out commits to the release
     130      branch without permission if the commit breaks the release branch.
     131
     132.. _django-developers: http://groups.google.com/group/django-developers
     133.. _ticket tracker: http://code.djangoproject.com/newticket

  • new file docs/internals/contributing/index.txt 

    diff --git a/docs/internals/contributing/index.txt b/docs/internals/contributing/index.txt
new file mode 100644
index 0000000..f145453
    - +  
     1======================
     2Contributing to Django
     3======================
     4
     5If you think working *with* Django is fun, wait until you start working *on*
     6it. We're passionate about helping Django users make the jump to contributing
     7members of the community, so there are several ways you can help Django's
     8development:
     9
     10    * Blog about Django. We syndicate all the Django blogs we know about on
     11      the `community page`_; if you'd like to see your blog on that page you
     12      can `register it here`_.
     13
     14    * :doc:`Report bugs and request features<bugs-and-features>` in our
     15      `ticket tracker`_.
     16
     17    * Join the `django-developers`_ mailing list and share your ideas for how
     18      to improve Django. We're always open to suggestions.
     19
     20    * :doc:`Submit patches<writing-code/submitting-patches>` for new and/or
     21      fixed behavior. If you're looking for an easy way to start contributing
     22      to Django have a look at the `easy pickings`_ tickets.
     23
     24    * :doc:`Improve the documentation<writing-documentation>` or
     25      :doc:`write unit tests<writing-code/unit-tests>`.
     26
     27    * :doc:`Triage tickets<triaging-tickets>` that have been created by other
     28      users.
     29
     30... and many more ways! Really, **ANYONE** can do something to help make Django
     31better and greater. Browse the following sections to find out how:
     32
     33.. toctree::
     34   :maxdepth: 2
     35
     36   new-contributors
     37   bugs-and-features
     38   triaging-tickets
     39   writing-code/index
     40   writing-documentation
     41   translations
     42   committing-code
     43   
     44
     45
     46.. _django-developers: http://groups.google.com/group/django-developers
     47.. _ticket tracker: http://code.djangoproject.com/newticket
     48.. _community page: http://www.djangoproject.com/community/
     49.. _`easy pickings`: http://code.djangoproject.com/query?status=!closed&easy=1
     50.. _`register it here`: http://www.djangoproject.com/community/add/blogs/

  • new file docs/internals/contributing/new-contributors.txt 

    diff --git a/docs/internals/contributing/new-contributors.txt b/docs/internals/contributing/new-contributors.txt
new file mode 100644
index 0000000..9aa8611
    - +  
     1===========================
     2Advice for new contributors
     3===========================
     4
     5New contributor and not sure what to do? Want to help but just don't know how
     6to get started? This is the section for you.
     7
     8* **Pick a subject area that you care about, that you are familiar with, or
     9  that you want to learn about**
     10
     11  You don't already have to be an expert on the area you want to work on; you
     12  become an expert through your ongoing contributions to the code.
     13
     14* **Triage tickets**
     15
     16  If a ticket is unreviewed and reports a bug, try and reproduce it. If you can
     17  reproduce it and it seems valid, make a note that you confirmed the bug and
     18  accept the ticket. Make sure the ticket is filed under the correct component
     19  area. Consider writing a patch that adds a test for the bug's behavior, even
     20  if you don't fix the bug itself. See more at
     21  :ref:`how-can-i-help-with-triaging`
     22
     23* **Look for tickets that are accepted and review patches to build familiarity
     24  with the codebase and the process**
     25
     26  Mark the appropriate flags if a patch needs docs or tests. Look through the
     27  changes a patch makes, and keep an eye out for syntax that is incompatible
     28  with older but still supported versions of Python. Run the tests and make
     29  sure they pass on your system.  Where possible and relevant, try them out on
     30  a database other than SQLite. Leave comments and feedback!
     31
     32* **Keep old patches up to date**
     33
     34  Oftentimes the codebase will change between a patch being submitted and the
     35  time it gets reviewed. Make sure it still applies cleanly and functions as
     36  expected. Simply updating a patch is both useful and important! See more on
     37  :doc:`writing-code/submitting-patches`.
     38
     39* **Write some documentation**
     40
     41  Django's documentation is great but it can always be improved. Did you find
     42  a typo? Do you think that something should be clarified? Go ahead and
     43  suggest a documentation patch! See also the guide on
     44  :doc:`writing-documentation`, in particular the tips for
     45  :ref:`improving-the-documentation`.
     46
     47* **Analyze the ticket's context and history**
     48
     49  Trac isn't an absolute; the context is just as important as the words.
     50  When reading Trac, you need to take into account who says things, and when
     51  they were said. Support for an idea two years ago doesn't necessarily mean
     52  that the idea will still have support. You also need to pay attention to who
     53  *hasn't* spoken -- for example, if a core team member hasn't been recently
     54  involved in a discussion, then a ticket may not have the support required to
     55  get into trunk.
     56
     57* **Start small**
     58
     59  It's easier to get feedback on a little issue than on a big one. See the
     60  `easy pickings`_.
     61
     62* **If you're going to engage in a big task, make sure that your idea has
     63  support first**
     64
     65  This means getting someone else to confirm that a bug is real before you fix
     66  the issue, and ensuring that the core team supports a proposed feature before
     67  you go implementing it.
     68
     69* **Be bold! Leave feedback!**
     70
     71  Sometimes it can be scary to put your opinion out to the world and say "this
     72  ticket is correct" or "this patch needs work", but it's the only way the
     73  project moves forward. The contributions of the broad Django community
     74  ultimately have a much greater impact than that of the core developers. We
     75  can't do it without YOU!
     76
     77* **Err on the side of caution when marking things Ready For Check-in**
     78
     79  If you're really not certain if a ticket is ready, don't mark it as
     80  such. Leave a comment instead, letting others know your thoughts.  If you're
     81  mostly certain, but not completely certain, you might also try asking on IRC
     82  to see if someone else can confirm your suspicions.
     83
     84* **Wait for feedback, and respond to feedback that you receive**
     85
     86  Focus on one or two tickets, see them through from start to finish, and
     87  repeat. The shotgun approach of taking on lots of tickets and letting some
     88  fall by the wayside ends up doing more harm than good.
     89
     90* **Be rigorous**
     91
     92  When we say ":pep:`8`, and must have docs and tests", we mean it. If a patch
     93  doesn't have docs and tests, there had better be a good reason. Arguments
     94  like "I couldn't find any existing tests of this feature" don't carry much
     95  weight--while it may be true, that means you have the extra-important job of
     96  writing the very first tests for that feature, not that you get a pass from
     97  writing tests altogether.
     98
     99.. note::
     100
     101    The `Reports page`_ contains links to many useful Trac queries, including
     102    several that are useful for triaging tickets and reviewing patches as
     103    suggested above.
     104
     105    .. _Reports page: http://code.djangoproject.com/wiki/Reports
     106
     107.. _new-contributors-faq:
     108
     109FAQ
     110---
     111
     1121. **This ticket I care about has been ignored for days/weeks/months! What can
     113   I do to get it committed?**
     114
     115   First off, it's not personal. Django is entirely developed by volunteers
     116   (even the core developers), and sometimes folks just don't have time. The
     117   best thing to do is to send a gentle reminder to the Django Developers
     118   mailing list asking for review on the ticket, or to bring it up in the
     119   #django-dev IRC channel.
     120
     1212. **I'm sure my ticket is absolutely 100% perfect, can I mark it as RFC
     122   myself?**
     123
     124   Short answer: No. It's always better to get another set of eyes on a
     125   ticket. If you're having trouble getting that second set of eyes, see
     126   question 1, above.
     127
     1283. **My ticket has been in DDN forever! What should I do?**
     129
     130   Design Decision Needed requires consensus about the right solution.  At the
     131   very least it needs consensus among the core developers, and ideally it has
     132   consensus from the community as well. The best way to accomplish this is to
     133   start a thread on the Django Developers mailing list, and for very complex
     134   issues to start a wiki page summarizing the problem and the possible
     135   solutions.
     136
     137.. _`easy pickings`: http://code.djangoproject.com/query?status=!closed&easy=1

  • new file docs/internals/contributing/translations.txt 

    diff --git a/docs/internals/contributing/translations.txt b/docs/internals/contributing/translations.txt
new file mode 100644
index 0000000..0c0a273
    - +  
     1=======================================
     2Submitting and maintaining translations
     3=======================================
     4
     5Various parts of Django, such as the admin site and validation error messages,
     6are internationalized. This means they display different text depending on a
     7user's language setting. For this, Django uses the same internationalization
     8infrastructure available to Django applications described in the
     9:doc:`i18n documentation</topics/i18n/index>`.
     10
     11These translations are contributed by Django users worldwide. If you find an
     12incorrect translation or want to discuss specific translations, go to the
     13`translation team`_ page for that language. If you would like to help out
     14with translating or add a language that isn't yet translated, here's what
     15to do:
     16
     17    * Join the `Django i18n mailing list`_ and introduce yourself.
     18
     19    * Make sure you read the notes about :ref:`specialties-of-django-i18n`.
     20
     21    * Signup at `Transifex`_ and visit the `Django project page`_.
     22
     23    * On the "`Translation Teams`_" page, choose the language team you want
     24      to work with, **or** -- in case the language team doesn't exist yet --
     25      request a new team by clicking on the "Request a new team" button
     26      and select the appropriate language.
     27
     28    * Then, click the "Join this Team" button to become a member of this team.
     29      Every team has at least one coordinator who is responsible to review
     30      your membership request. You can of course also contact the team
     31      coordinator to clarify procedural problems and handle the actual
     32      translation process.
     33
     34    * Once you are a member of a team choose the translation resource you
     35      want update on the team page. For example the "core" resource refers
     36      to the translation catalogue that contains all non-app translations.
     37      Each of the contrib apps also have a resource (prefixed with "contrib-").
     38
     39      .. note::
     40         For more information about how to use Transifex, see the
     41         `Transifex Help`_
     42
     43    * Optionally, review and update the ``conf/locale/<locale>/formats.py``
     44      file to describe the date, time and numbers formatting particularities
     45      of your locale. These files aren't covered by the use of Transifex and
     46      require a patch against the Django source tree, just as a code change
     47      would:
     48
     49      * Create a diff against the current Subversion trunk.
     50
     51      * Open a ticket in Django's ticket system, set its ``Component`` field
     52        to ``Translations``, and attach the patch to it. See
     53        :ref:`format-localization` for details.
     54
     55.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
     56.. _Transifex: http://www.transifex.net/
     57.. _Django project page: http://www.transifex.net/projects/p/django/
     58.. _translation teams: http://www.transifex.net/projects/p/django/teams/
     59.. _translation team: http://www.transifex.net/projects/p/django/teams/
     60.. _Transifex Help: http://help.transifex.net/

  • new file docs/internals/contributing/triaging-tickets.txt 

    diff --git a/docs/internals/contributing/triaging-tickets.txt b/docs/internals/contributing/triaging-tickets.txt
new file mode 100644
index 0000000..57c819a
    - +  
     1================
     2Triaging tickets
     3================
     4
     5Django uses Trac_ for managing our progress, and Trac is a community-tended
     6garden of the bugs people have found and the features people would like to see
     7added. As in any garden, sometimes there are weeds to be pulled and sometimes
     8there are flowers and vegetables that need picking. We need your help to sort
     9out one from the other, and in the end we all benefit together.
     10
     11Like all gardens, we can aspire to perfection but in reality there's no such
     12thing. Even in the most pristine garden there are still snails and insects. In
     13a community garden there are also helpful people who--with the best of
     14intentions--fertilize the weeds and poison the roses. It's the job of the
     15community as a whole to self-manage, keep the problems to a minimum, and
     16educate those coming into the community so that they can become valuable
     17contributing members.
     18
     19Similarly, while we aim for Trac to be a perfect representation of the state of
     20Django's progress, we acknowledge that this simply will not happen. By
     21distributing the load of Trac maintenance to the community, we accept that
     22there will be mistakes. Trac is "mostly accurate", and we give allowances for
     23the fact that sometimes it will be wrong. That's okay. We're perfectionists
     24with deadlines.
     25
     26We rely on the community to keep participating, keep tickets as accurate as
     27possible, and raise issues for discussion on our mailing lists when there is
     28confusion or disagreement.
     29
     30Django is a community project, and every contribution helps. We can't do this
     31without YOU!
     32
     33Triage workflow
     34---------------
     35
     36Unfortunately, not all bug reports and feature requests in the ticket tracker
     37provide all the :doc:`required details<bugs-and-features>`. A number of tickets
     38have patches, but those patches don't meet all the requirements of a
     39:ref:`good patch<patch-style>`.
     40
     41One way to help out is to *triage* tickets that have been created by other
     42users. The core team--as well as many community members--work on this
     43regularly, but more help is always appreciated.
     44
     45Most of the workflow is based around the concept of a ticket's
     46:ref:`triage stages <triage-stages>`. Each stage describes where in its
     47lifetime a given ticket is at any time. Along with a handful of flags, this
     48attribute easily tells us what and who each ticket is waiting on.
     49
     50Since a picture is worth a thousand words, let's start there:
     51
     52.. image:: /internals/_images/djangotickets.png
     53   :height: 451
     54   :width: 590
     55   :alt: Django's ticket triage workflow
     56
     57We've got two roles in this diagram:
     58
     59    * :doc:`Committers</internals/committers>` (also called core developers):
     60      people with commit access who are responsible for making the big
     61      decisions, writing large portions of the code and integrating the
     62      contributions of the community.
     63
     64    * Ticket triagers: anyone in the Django community who chooses to
     65      become involved in Django's development process. Our Trac installation
     66      is intentionally left open to the public, and anyone can triage tickets.
     67      Django is a community project, and we encourage :ref:`triage by the
     68      community<how-can-i-help-with-triaging>`.
     69
     70By way of example, here we see the lifecycle of an average ticket:
     71
     72* Alice creates a ticket, and uploads an incomplete patch (no tests, incorrect
     73  implementation).
     74
     75* Bob reviews the patch, marks it "Accepted", "needs tests", and "patch needs
     76  improvement", and leaves a comment telling Alice how the patch could be
     77  improved.
     78
     79* Alice updates the patch, adding tests (but not changing the
     80  implementation). She removes the two flags.
     81
     82* Charlie reviews the patch and resets the "patch needs improvement" flag with
     83  another comment about improving the implementation.
     84
     85* Alice updates the patch, fixing the implementation. She removes the "patch
     86  needs improvement" flag.
     87
     88* Daisy reviews the patch, and marks it RFC.
     89
     90* Jacob, a core developer, reviews the RFC patch, applies it to his checkout,
     91  and commits it.
     92
     93Some tickets require much less feedback than this, but then again some tickets
     94require much much more.
     95
     96.. _triage-stages:
     97
     98Triage stages
     99-------------
     100
     101Below we describe in more detail the various stages that a ticket may flow
     102through during its lifetime.
     103
     104Unreviewed
     105~~~~~~~~~~
     106
     107The ticket has not been reviewed by anyone who felt qualified to make a
     108judgment about whether the ticket contained a valid issue, a viable feature,
     109or ought to be closed for any of the various reasons.
     110
     111Accepted
     112~~~~~~~~
     113
     114The big grey area! The absolute meaning of "accepted" is that the issue
     115described in the ticket is valid and is in some stage of being worked on.
     116Beyond that there are several considerations:
     117
     118* **Accepted + No Flags**
     119
     120  The ticket is valid, but no one has submitted a patch for it yet. Often this
     121  means you could safely start writing a patch for it.
     122
     123* **Accepted + Has Patch**
     124
     125  The ticket is waiting for people to review the supplied patch. This means
     126  downloading the patch and trying it out, verifying that it contains tests and
     127  docs, running the test suite with the included patch, and leaving feedback on
     128  the ticket.
     129
     130* **Accepted + Has Patch + (any other flag)**
     131
     132  This means the ticket has been reviewed, and has been found to need further
     133  work. "Needs tests" and "Needs documentation" are self-explanatory. "Patch
     134  needs improvement" will generally be accompanied by a comment on the ticket
     135  explaining what is needed to improve the code.
     136
     137Design Decision Needed
     138~~~~~~~~~~~~~~~~~~~~~~
     139
     140This stage is for issues which may be contentious, may be backwards
     141incompatible, or otherwise involve high-level design decisions. These issues
     142should be discussed either in the ticket comments or on `django-developers`_.
     143
     144If a ticket has been marked as "DDN", decisions are generally eventually
     145made by the core committers, however that is not a requirement. See the
     146:ref:`New contributors' FAQ<new-contributors-faq>` for "My ticket has been in
     147DDN forever! What should I do?"
     148
     149This stage will generally only be used for feature
     150requests. It can also be used for issues that *might* be bugs, depending on
     151opinion or interpretation. Obvious bugs (such as crashes, incorrect query
     152results, or non-compliance with a standard) skip this stage and move straight
     153to "Accepted".
     154
     155Ready For Checkin
     156~~~~~~~~~~~~~~~~~
     157
     158The ticket was reviewed by any member of the community other than the person
     159who supplied the patch and found to meet all the requirements for a
     160commit-ready patch. A core committer now needs to give the patch a final review
     161prior to being committed. See the
     162:ref:`New contributors' FAQ<new-contributors-faq>` for "My ticket has been in
     163RFC forever! What should I do?"
     164
     165Someday/Maybe
     166~~~~~~~~~~~~~
     167
     168Generally only used for vague/high-level features or design ideas. These
     169tickets are uncommon and overall less useful since they don't describe concrete
     170actionable issues. They are enhancement requests that we might consider
     171adding someday to the framework if an excellent patch is submitted. These
     172tickets are not a high priority.
     173
     174Fixed on a branch
     175~~~~~~~~~~~~~~~~~
     176
     177Used to indicate that a ticket is resolved as part of a major body of work that
     178will eventually be merged to trunk.  Tickets in this stage generally don't need
     179further work. This may happen in the case of major features/refactors in each
     180release cycle, or as part of the annual Google Summer of Code efforts.
     181
     182Other triage attributes
     183-----------------------
     184
     185A number of flags, appearing as checkboxes in Trac, can be set on a ticket:
     186
     187  * Has patch
     188        This means the ticket has an associated
     189        :doc:`patch<writing-code/submitting-patches>`. These will be reviewed
     190        to see if the patch is "good".
     191  * Needs documentation:
     192        This flag is used for tickets with patches that need associated
     193        documentation. Complete documentation of features is a prerequisite
     194        before we can check them into the codebase.
     195  * Needs tests
     196        This flags the patch as needing associated unit tests. Again, this is a
     197        required part of a valid patch.
     198  * Patch needs improvement
     199        This flag means that although the ticket *has* a patch, it's not quite
     200        ready for checkin. This could mean the patch no longer applies
     201        cleanly, there is a flaw in the implementation, or that the code
     202        doesn't meet our standards."` 
     203  * Easy pickings
     204        Tickets that would require small, easy, patches.
     205
     206Tickets should be categorized by *type* between:
     207
     208  * New Feature
     209        For adding something new.
     210
     211  * Bug
     212        For when an existing thing is broken or not behaving as expected.
     213
     214  * Cleanup/optimization
     215        For when nothing is broken but something could be made cleaner,
     216        better, faster, stronger.
     217
     218Tickets should also be classified into *components* indicating which area of
     219the Django codebase they belong to. This makes tickets better organized and
     220easier to find.
     221
     222The *severity* attribute is used to identify blockers, that is, issues which
     223should get fixed before releasing the next version of Django. Typically those
     224issues are bugs causing regressions from earlier versions or potentially
     225causing severe data losses. This attribute is quite rarely used and the vast
     226majority of tickets have a severity of "Normal".
     227
     228Finally, it is possible to use the *version* attribute to indicate in which
     229version the reported bug was identified.
     230
     231.. _closing-tickets:
     232
     233Closing Tickets
     234---------------
     235
     236When a ticket has completed its useful lifecycle, it's time for it to be
     237closed. Closing a ticket is a big responsibility, though. You have to be sure
     238that the issue is really resolved, and you need to keep in mind that the
     239reporter of the ticket may not be happy to have their ticket closed (unless
     240it's fixed, of course). If you're not certain about closing a ticket, just
     241leave a comment with your thoughts instead.
     242
     243If you do close a ticket, you should always make sure of the following:
     244
     245  * Be certain that the issue is resolved.
     246
     247  * Leave a comment explaining the decision to close the ticket.
     248
     249  * If there is a way they can improve the ticket to reopen it, let them know.
     250
     251  * If the ticket is a duplicate, reference the original ticket. Also
     252    cross-reference the closed ticket by living a comment in the original one
     253    -- this allows to access more related information about the reported bug or
     254    requested feature.
     255
     256  * **Be polite.** No one likes having their ticket closed. It can be
     257    frustrating or even discouraging. The best way to avoid turning people
     258    off from contributing to Django is to be polite and friendly and to offer
     259    suggestions for how they could improve this ticket and other tickets in the
     260    future.
     261
     262A ticket can be resolved in a number of ways:
     263
     264  * fixed
     265        Used by the core developers once a patch has been rolled into
     266        Django and the issue is fixed.
     267
     268  * invalid
     269        Used if the ticket is found to be incorrect. This means that the
     270        issue in the ticket is actually the result of a user error, or
     271        describes a problem with something other than Django, or isn't
     272        a bug report or feature request at all (for example, some new users
     273        submit support queries as tickets).
     274
     275  * wontfix
     276        Used when a core developer decides that this request is not
     277        appropriate for consideration in Django. This is usually chosen after
     278        discussion in the `django-developers`_ mailing list. Feel free to
     279        start or join in discussions of "wontfix" tickets on the
     280        django-developers_ mailing list, but please do not reopen tickets
     281        closed as "wontfix" by core developers.
     282
     283  * duplicate
     284        Used when another ticket covers the same issue. By closing duplicate
     285        tickets, we keep all the discussion in one place, which helps everyone.
     286
     287  * worksforme
     288        Used when the ticket doesn't contain enough detail to replicate
     289        the original bug.
     290
     291  * needsinfo
     292        Used when the ticket does not contain enough information to replicate
     293        the reported issue but is potentially still valid. The ticket
     294        should be reopened when more information is supplied.
     295
     296If you believe that the ticket was closed in error -- because you're
     297still having the issue, or it's popped up somewhere else, or the triagers have
     298made a mistake -- please reopen the ticket and provide further information.
     299Again, please do not reopen tickets that have been marked as "wontfix" by core
     300developers and bring the issue to django-developers_ instead.
     301
     302.. _how-can-i-help-with-triaging:
     303
     304How can I help with triaging?
     305-----------------------------
     306
     307Although the core developers make the big decisions in the ticket triage
     308process, there's a lot that general community members can do to help the
     309triage process. Really, **ANYONE** can help.
     310
     311Start by `creating an account on Trac`_. If you have an account but have
     312forgotten your password, you can reset it using the `password reset page`_.
     313
     314Then, you can help out by:
     315
     316    * Closing "Unreviewed" tickets as "invalid", "worksforme" or "duplicate."
     317
     318    * Promoting "Unreviewed" tickets to "Design decision needed" if a design
     319      decision needs to be made, or "Accepted" in case of obvious bugs or
     320      sensible, clearly defined, feature requests.
     321
     322    * Correcting the "Needs tests", "Needs documentation", or "Has patch"
     323      flags for tickets where they are incorrectly set.
     324
     325    * Setting the "`Easy pickings`_" flag for tickets that are small and
     326      relatively straightforward.
     327
     328    * Checking that old tickets are still valid. If a ticket hasn't seen
     329      any activity in a long time, it's possible that the problem has been
     330      fixed but the ticket hasn't yet been closed.
     331
     332    * Contacting the owners of tickets that have been claimed but have not
     333      seen any recent activity. If the owner doesn't respond after a week
     334      or so, remove the owner's claim on the ticket.
     335
     336    * Identifying trends and themes in the tickets. If there a lot of bug
     337      reports about a particular part of Django, it may indicate we should
     338      consider refactoring that part of the code. If a trend is emerging,
     339      you should raise it for discussion (referencing the relevant tickets)
     340      on `django-developers`_.
     341     
     342    * Set the *type* of tickets that are still uncategorized.
     343   
     344    * Verify if patches submitted by other users are correct. If they do and
     345      also contain appropriate documentation and tests then move them to the
     346      "Ready for Checkin" stage. If they don't then leave a comment to explain
     347      why and set the corresponding flags ("Patch needs improvement",
     348      "Needs tests" etc.).
     349
     350.. note::
     351
     352    The `Reports page`_ contains links to many useful Trac queries, including
     353    several that are useful for triaging tickets and reviewing patches as
     354    suggested above.
     355
     356    You can also find more :doc:`new-contributors`.
     357
     358    .. _Reports page: http://code.djangoproject.com/wiki/Reports
     359
     360However, we do ask the following of all general community members working in
     361the ticket database:
     362
     363    * Please **don't** close tickets as "wontfix." The core developers will
     364      make the final determination of the fate of a ticket, usually after
     365      consultation with the community.
     366
     367    * Please **don't** promote your own tickets to "Ready for checkin". You
     368      may mark other people's tickets which you've reviewed as "Ready for
     369      checkin", but you should get at minimum one other community member to
     370      review a patch that you submit.
     371
     372    * Please **don't** reverse a decision that has been made by a core
     373      developer. If you disagree with a decision that has been made,
     374      please post a message to `django-developers`_.
     375
     376    * If you're unsure if you should be making a change, don't make the change
     377      but instead leave a comment with your concerns on the ticket, or
     378      post a message to `django-developers`_. It's okay to be unsure, but
     379      your input is still valuable.
     380
     381.. _Trac: http://code.djangoproject.com/
     382.. _django-developers: http://groups.google.com/group/django-developers
     383.. _i18n branch: http://code.djangoproject.com/browser/django/branches/i18n
     384.. _`tags/releases`: http://code.djangoproject.com/browser/django/tags/releases
     385.. _`easy pickings`: http://code.djangoproject.com/query?status=!closed&easy=1
     386.. _`creating an account on Trac`: http://www.djangoproject.com/accounts/register/
     387.. _password reset page: http://www.djangoproject.com/accounts/password/reset/

  • new file docs/internals/contributing/writing-code/branch-policy.txt 

    diff --git a/docs/internals/contributing/writing-code/branch-policy.txt b/docs/internals/contributing/writing-code/branch-policy.txt
new file mode 100644
index 0000000..b587f51
    - +  
     1=============
     2Branch policy
     3=============
     4
     5In general, the trunk must be kept stable. People should be able to run
     6production sites against the trunk at any time. Additionally, commits to trunk
     7ought to be as atomic as possible -- smaller changes are better. Thus, large
     8feature changes -- that is, changes too large to be encapsulated in a single
     9patch, or changes that need multiple eyes on them -- must happen on dedicated
     10branches.
     11
     12This means that if you want to work on a large feature -- anything that would
     13take more than a single patch, or requires large-scale refactoring -- you need
     14to do it on a feature branch. Our development process recognizes two options
     15for feature branches:
     16
     17    1. Feature branches using a distributed revision control system like
     18       Git_, Mercurial_, Bazaar_, etc.
     19
     20       If you're familiar with one of these tools, this is probably your best
     21       option since it doesn't require any support or buy-in from the Django
     22       core developers.
     23
     24       However, do keep in mind that Django will continue to use Subversion for
     25       the foreseeable future, and this will naturally limit the recognition of
     26       your branch. Further, if your branch becomes eligible for merging to
     27       trunk you'll need to find a core developer familiar with your DVCS of
     28       choice who'll actually perform the merge.
     29
     30       If you do decided to start a distributed branch of Django and choose to
     31       make it public, please add the branch to the `Django branches`_ wiki
     32       page.
     33
     34    2. Feature branches using SVN have a higher bar. If you want a branch
     35       in SVN itself, you'll need a "mentor" among the :doc:`core committers
     36       </internals/committers>`. This person is responsible for actually
     37       creating the branch, monitoring your process (see below), and
     38       ultimately merging the branch into trunk.
     39
     40       If you want a feature branch in SVN, you'll need to ask in
     41       `django-developers`_ for a mentor.
     42
     43.. _git: http://git-scm.com/
     44.. _mercurial: http://mercurial.selenic.com/
     45.. _bazaar: http://bazaar.canonical.com/
     46.. _django branches: http://code.djangoproject.com/wiki/DjangoBranches
     47
     48Branch rules
     49------------
     50
     51We've got a few rules for branches born out of experience with what makes a
     52successful Django branch.
     53
     54DVCS branches are obviously not under central control, so we have no way of
     55enforcing these rules. However, if you're using a DVCS, following these rules
     56will give you the best chance of having a successful branch (read: merged back
     57to trunk).
     58
     59Developers with branches in SVN, however, **must** follow these rules. The
     60branch mentor will keep on eye on the branch and **will delete it** if these
     61rules are broken.
     62
     63    * Only branch entire copies of the Django tree, even if work is only
     64      happening on part of that tree. This makes it painless to switch to a
     65      branch.
     66
     67    * Merge changes from trunk no less than once a week, and preferably every
     68      couple-three days.
     69
     70      In our experience, doing regular trunk merges is often the difference
     71      between a successful branch and one that fizzles and dies.
     72
     73      If you're working on an SVN branch, you should be using `svnmerge.py`_
     74      to track merges from trunk.
     75
     76    * Keep tests passing and documentation up-to-date. As with patches,
     77      we'll only merge a branch that comes with tests and documentation.
     78
     79.. _svnmerge.py: http://www.orcaware.com/svn/wiki/Svnmerge.py
     80
     81Once the branch is stable and ready to be merged into the trunk, alert
     82`django-developers`_.
     83
     84After a branch has been merged, it should be considered "dead"; write access to
     85it will be disabled, and old branches will be periodically "trimmed." To keep
     86our SVN wrangling to a minimum, we won't be merging from a given branch into
     87the trunk more than once.
     88
     89Using branches
     90--------------
     91
     92To use a branch, you'll need to do two things:
     93
     94    * Get the branch's code through Subversion.
     95
     96    * Point your Python ``site-packages`` directory at the branch's version of
     97      the ``django`` package rather than the version you already have
     98      installed.
     99
     100Getting the code from Subversion
     101~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     102
     103To get the latest version of a branch's code, check it out using Subversion:
     104
     105.. code-block:: bash
     106
     107    svn co http://code.djangoproject.com/svn/django/branches/<branch>/
     108
     109...where ``<branch>`` is the branch's name. See the `list of branch names`_.
     110
     111Alternatively, you can automatically convert an existing directory of the
     112Django source code as long as you've checked it out via Subversion. To do the
     113conversion, execute this command from within your ``django`` directory:
     114
     115.. code-block:: bash
     116
     117    svn switch http://code.djangoproject.com/svn/django/branches/<branch>/
     118
     119The advantage of using ``svn switch`` instead of ``svn co`` is that the
     120``switch`` command retains any changes you might have made to your local copy
     121of the code. It attempts to merge those changes into the "switched" code. The
     122disadvantage is that it may cause conflicts with your local changes if the
     123"switched" code has altered the same lines of code.
     124
     125(Note that if you use ``svn switch``, you don't need to point Python at the new
     126version, as explained in the next section.)
     127
     128.. _list of branch names: http://code.djangoproject.com/browser/django/branches
     129
     130.. _pointing-python-at-the-new-django-version:
     131
     132Pointing Python at the new Django version
     133~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     134
     135Once you've retrieved the branch's code, you'll need to change your Python
     136``site-packages`` directory so that it points to the branch version of the
     137``django`` directory. (The ``site-packages`` directory is somewhere such as
     138``/usr/lib/python2.4/site-packages`` or
     139``/usr/local/lib/python2.4/site-packages`` or ``C:\Python\site-packages``.)
     140
     141The simplest way to do this is by renaming the old ``django`` directory to
     142``django.OLD`` and moving the trunk version of the code into the directory
     143and calling it ``django``.
     144
     145Alternatively, you can use a symlink called ``django`` that points to the
     146location of the branch's ``django`` package. If you want to switch back, just
     147change the symlink to point to the old code.
     148
     149A third option is to use a `path file`_ (``<something>.pth``) which should
     150work on all systems (including Windows, which doesn't have symlinks
     151available). First, make sure there are no files, directories or symlinks named
     152``django`` in your ``site-packages`` directory. Then create a text file named
     153``django.pth`` and save it to your ``site-packages`` directory. That file
     154should contain a path to your copy of Django on a single line and optional
     155comments. Here is an example that points to multiple branches. Just uncomment
     156the line for the branch you want to use ('Trunk' in this example) and make
     157sure all other lines are commented::
     158
     159    # Trunk is a svn checkout of:
     160    #   http://code.djangoproject.com/svn/django/trunk/
     161    #
     162    /path/to/trunk
     163
     164    # <branch> is a svn checkout of:
     165    #   http://code.djangoproject.com/svn/django/branches/<branch>/
     166    #
     167    #/path/to/<branch>
     168
     169    # On windows a path may look like this:
     170    # C:/path/to/<branch>
     171
     172If you're using Django 0.95 or earlier and installed it using
     173``python setup.py install``, you'll have a directory called something like
     174``Django-0.95-py2.4.egg`` instead of ``django``. In this case, edit the file
     175``setuptools.pth`` and remove the line that references the Django ``.egg``
     176file. Then copy the branch's version of the ``django`` directory into
     177``site-packages``.
     178
     179.. _path file: http://docs.python.org/library/site.html
     180.. _django-developers: http://groups.google.com/group/django-developers

  • new file docs/internals/contributing/writing-code/coding-style.txt 

    diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt
new file mode 100644
index 0000000..4433fef
    - +  
     1============
     2Coding Style
     3============
     4
     5Please follow these coding standards when writing code for inclusion in Django.
     6
     7Python style
     8------------
     9
     10    * Unless otherwise specified, follow :pep:`8`.
     11
     12      You could use a tool like `pep8.py`_ to check for some problems in this
     13      area, but remember that PEP 8 is only a guide, so respect the style of
     14      the surrounding code as a primary goal.
     15
     16    * Use four spaces for indentation.
     17
     18    * Use underscores, not camelCase, for variable, function and method names
     19      (i.e. ``poll.get_unique_voters()``, not ``poll.getUniqueVoters``).
     20
     21    * Use ``InitialCaps`` for class names (or for factory functions that
     22      return classes).
     23
     24    * In docstrings, use "action words" such as::
     25
     26          def foo():
     27              """
     28              Calculates something and returns the result.
     29              """
     30              pass
     31
     32      Here's an example of what not to do::
     33
     34          def foo():
     35              """
     36              Calculate something and return the result.
     37              """
     38              pass
     39
     40Template style
     41--------------
     42
     43    * In Django template code, put one (and only one) space between the curly
     44      brackets and the tag contents.
     45
     46      Do this:
     47
     48      .. code-block:: html+django
     49
     50          {{ foo }}
     51
     52      Don't do this:
     53
     54      .. code-block:: html+django
     55
     56          {{foo}}
     57
     58View style
     59----------
     60
     61    * In Django views, the first parameter in a view function should be called
     62      ``request``.
     63
     64      Do this::
     65
     66          def my_view(request, foo):
     67              # ...
     68
     69      Don't do this::
     70
     71          def my_view(req, foo):
     72              # ...
     73
     74Model style
     75-----------
     76
     77    * Field names should be all lowercase, using underscores instead of
     78      camelCase.
     79
     80      Do this::
     81
     82          class Person(models.Model):
     83              first_name = models.CharField(max_length=20)
     84              last_name = models.CharField(max_length=40)
     85
     86      Don't do this::
     87
     88          class Person(models.Model):
     89              FirstName = models.CharField(max_length=20)
     90              Last_Name = models.CharField(max_length=40)
     91
     92    * The ``class Meta`` should appear *after* the fields are defined, with
     93      a single blank line separating the fields and the class definition.
     94
     95      Do this::
     96
     97          class Person(models.Model):
     98              first_name = models.CharField(max_length=20)
     99              last_name = models.CharField(max_length=40)
     100
     101              class Meta:
     102                  verbose_name_plural = 'people'
     103
     104      Don't do this::
     105
     106          class Person(models.Model):
     107              first_name = models.CharField(max_length=20)
     108              last_name = models.CharField(max_length=40)
     109              class Meta:
     110                  verbose_name_plural = 'people'
     111
     112      Don't do this, either::
     113
     114          class Person(models.Model):
     115              class Meta:
     116                  verbose_name_plural = 'people'
     117
     118              first_name = models.CharField(max_length=20)
     119              last_name = models.CharField(max_length=40)
     120
     121    * The order of model inner classes and standard methods should be as
     122      follows (noting that these are not all required):
     123
     124        * All database fields
     125        * Custom manager attributes
     126        * ``class Meta``
     127        * ``def __unicode__()``
     128        * ``def __str__()``
     129        * ``def save()``
     130        * ``def get_absolute_url()``
     131        * Any custom methods
     132
     133    * If ``choices`` is defined for a given model field, define the choices as
     134      a tuple of tuples, with an all-uppercase name, either near the top of the
     135      model module or just above the model class. Example::
     136
     137          GENDER_CHOICES = (
     138              ('M', 'Male'),
     139              ('F', 'Female'),
     140          )
     141
     142Use of ``django.conf.settings``
     143-------------------------------
     144
     145Modules should not in general use settings stored in ``django.conf.settings``
     146at the top level (i.e. evaluated when the module is imported). The explanation
     147for this is as follows:
     148
     149Manual configuration of settings (i.e. not relying on the
     150``DJANGO_SETTINGS_MODULE`` environment variable) is allowed and possible as
     151follows::
     152
     153    from django.conf import settings
     154
     155    settings.configure({}, SOME_SETTING='foo')
     156
     157However, if any setting is accessed before the ``settings.configure`` line,
     158this will not work. (Internally, ``settings`` is a ``LazyObject`` which
     159configures itself automatically when the settings are accessed if it has not
     160already been configured).
     161
     162So, if there is a module containing some code as follows::
     163
     164    from django.conf import settings
     165    from django.core.urlresolvers import get_callable
     166
     167    default_foo_view = get_callable(settings.FOO_VIEW)
     168
     169...then importing this module will cause the settings object to be configured.
     170That means that the ability for third parties to import the module at the top
     171level is incompatible with the ability to configure the settings object
     172manually, or makes it very difficult in some circumstances.
     173
     174Instead of the above code, a level of laziness or indirection must be used,
     175such as `django.utils.functional.LazyObject``, ``django.utils.functional.lazy``
     176or ``lambda``.
     177
     178Miscellaneous
     179-------------
     180
     181    * Mark all strings for internationalization; see the :doc:`i18n
     182      documentation </topics/i18n/index>` for details.
     183
     184    * Please don't put your name in the code you contribute. Our policy is to
     185      keep contributors' names in the ``AUTHORS`` file distributed with Django
     186      -- not scattered throughout the codebase itself. Feel free to include a
     187      change to the ``AUTHORS`` file in your patch if you make more than a
     188      single trivial change.
     189
     190.. _pep8.py: http://pypi.python.org/pypi/pep8/

  • new file docs/internals/contributing/writing-code/index.txt 

    diff --git a/docs/internals/contributing/writing-code/index.txt b/docs/internals/contributing/writing-code/index.txt
new file mode 100644
index 0000000..444cb93
    - +  
     1============
     2Writing code
     3============
     4
     5So you'd like to write some code to improve Django. Awesome! Browse the
     6following sections to find out how to give your code patches the best chances
     7to be included in Django core:
     8
     9.. toctree::
     10   :maxdepth: 1
     11
     12   coding-style
     13   unit-tests
     14   submitting-patches
     15   branch-policy

  • new file docs/internals/contributing/writing-code/submitting-patches.txt 

    diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt
new file mode 100644
index 0000000..4fa449e
    - +  
     1==================
     2Submitting patches
     3==================
     4
     5We're always grateful for patches to Django's code. Indeed, bug reports
     6with associated patches will get fixed *far* more quickly than those
     7without patches.
     8
     9"Claiming" tickets
     10------------------
     11
     12In an open-source project with hundreds of contributors around the world, it's
     13important to manage communication efficiently so that work doesn't get
     14duplicated and contributors can be as effective as possible. Hence, our policy
     15is for contributors to "claim" tickets in order to let other developers know
     16that a particular bug or feature is being worked on.
     17
     18If you have identified a contribution you want to make and you're capable of
     19fixing it (as measured by your coding ability, knowledge of Django internals
     20and time availability), claim it by following these steps:
     21
     22    * `Create an account`_ to use in our ticket system. If you have an account
     23      but have forgotten your password, you can reset it using the
     24      `password reset page`_.
     25
     26    * If a ticket for this issue doesn't exist yet, create one in our
     27      `ticket tracker`_.
     28
     29    * If a ticket for this issue already exists, make sure nobody else has
     30      claimed it. To do this, look at the "Assigned to" section of the ticket.
     31      If it's assigned to "nobody," then it's available to be claimed.
     32      Otherwise, somebody else is working on this ticket, and you either find
     33      another bug/feature to work on, or contact the developer working on the
     34      ticket to offer your help.
     35
     36    * Log into your account, if you haven't already, by clicking "Login" in the
     37      upper right of the ticket page.
     38
     39    * Claim the ticket by clicking the radio button next to "Accept ticket"
     40      near the bottom of the page, then clicking "Submit changes."
     41
     42.. _Create an account: http://www.djangoproject.com/accounts/register/
     43.. _password reset page: http://www.djangoproject.com/accounts/password/reset/
     44
     45Ticket claimers' responsibility
     46~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     47
     48Once you've claimed a ticket, you have a responsibility to work on that ticket
     49in a reasonably timely fashion. If you don't have time to work on it, either
     50unclaim it or don't claim it in the first place!
     51
     52If there's no sign of progress on a particular claimed ticket for a week or
     53two, another developer may ask you to relinquish the ticket claim so that it's
     54no longer monopolized and somebody else can claim it.
     55
     56If you've claimed a ticket and it's taking a long time (days or weeks) to code,
     57keep everybody updated by posting comments on the ticket. If you don't provide
     58regular updates, and you don't respond to a request for a progress report,
     59your claim on the ticket may be revoked. As always, more communication is
     60better than less communication!
     61
     62Which tickets should be claimed?
     63~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     64
     65Of course, going through the steps of claiming tickets is overkill in some
     66cases. In the case of small changes, such as typos in the documentation or
     67small bugs that will only take a few minutes to fix, you don't need to jump
     68through the hoops of claiming tickets. Just submit your patch and be done with
     69it.
     70
     71.. _patch-style:
     72
     73Patch style
     74-----------
     75
     76    * Make sure your code matches our :doc:`coding-style`.
     77
     78    * Submit patches in the format returned by the ``svn diff`` command.
     79      An exception is for code changes that are described more clearly in
     80      plain English than in code. Indentation is the most common example; it's
     81      hard to read patches when the only difference in code is that it's
     82      indented.
     83
     84      Patches in ``git diff`` format are also acceptable.
     85
     86    * When creating patches, always run ``svn diff`` from the top-level
     87      ``trunk`` directory -- i.e., the one that contains ``django``, ``docs``,
     88      ``tests``, ``AUTHORS``, etc. This makes it easy for other people to
     89      apply your patches.
     90
     91    * Attach patches to a ticket in the `ticket tracker`_, using the "attach
     92      file" button. Please *don't* put the patch in the ticket description
     93      or comment unless it's a single line patch.
     94
     95    * Name the patch file with a ``.diff`` extension; this will let the ticket
     96      tracker apply correct syntax highlighting, which is quite helpful.
     97
     98    * Check the "Has patch" box on the ticket details. This will make it
     99      obvious that the ticket includes a patch, and it will add the ticket to
     100      the `list of tickets with patches`_.
     101
     102    * The code required to fix a problem or add a feature is an essential part
     103      of a patch, but it is not the only part. A good patch should also include
     104      a regression test to validate the behavior that has been fixed
     105      (and prevent the problem from arising again).
     106
     107    * If the code associated with a patch adds a new feature, or modifies
     108      behavior of an existing feature, the patch should also contain
     109      documentation.
     110
     111Non-trivial patches
     112-------------------
     113
     114A "non-trivial" patch is one that is more than a simple bug fix. It's a patch
     115that introduces Django functionality and makes some sort of design decision.
     116
     117If you provide a non-trivial patch, include evidence that alternatives have
     118been discussed on `django-developers`_. If you're not sure whether your patch
     119should be considered non-trivial, just ask.
     120
     121Javascript patches
     122------------------
     123
     124.. versionadded:: 1.2
     125
     126Django's admin system leverages the jQuery framework to increase the
     127capabilities of the admin interface. In conjunction, there is an emphasis on
     128admin javascript performance and minimizing overall admin media file size.
     129Serving compressed or "minified" versions of javascript files is considered
     130best practice in this regard.
     131
     132To that end, patches for javascript files should include both the original
     133code for future development (e.g. "foo.js"), and a compressed version for
     134production use (e.g. "foo.min.js"). Any links to the file in the codebase
     135should point to the compressed version.
     136
     137To simplify the process of providing optimized javascript code, Django
     138includes a handy script which should be used to create a "minified" version.
     139This script is located at ``/contrib/admin/media/js/compress.py``.
     140
     141Behind the scenes, ``compress.py`` is a front-end for Google's
     142`Closure Compiler`_ which is written in Java. However, the Closure Compiler
     143library is not bundled with Django directly, so those wishing to contribute
     144complete javascript patches will need to download and install the library
     145independently.
     146
     147The Closure Compiler library requires Java version 6 or higher (Java 1.6 or
     148higher on Mac OS X). Note that Mac OS X 10.5 and earlier did not ship with Java
     1491.6 by default, so it may be necessary to upgrade your Java installation before
     150the tool will be functional. Also note that even after upgrading Java, the
     151default `/usr/bin/java` command may remain linked to the previous Java
     152binary, so relinking that command may be necessary as well.
     153
     154Please don't forget to run ``compress.py`` and include the ``diff`` of the
     155minified scripts when submitting patches for Django's javascript.
     156
     157.. _Closure Compiler: http://code.google.com/closure/compiler/
     158.. _django-developers: http://groups.google.com/group/django-developers
     159.. _list of tickets with patches: http://code.djangoproject.com/query?status=new&status=assigned&status=reopened&has_patch=1&order=priority
     160.. _ticket tracker: http://code.djangoproject.com/newticket

  • new file docs/internals/contributing/writing-code/unit-tests.txt 

    diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt
new file mode 100644
index 0000000..6db8a86
    - +  
     1==========
     2Unit tests
     3==========
     4
     5Django comes with a test suite of its own, in the ``tests`` directory of the
     6Django tarball. It's our policy to make sure all tests pass at all times.
     7
     8The tests cover:
     9
     10    * Models and the database API (``tests/modeltests/``).
     11    * Everything else in core Django code (``tests/regressiontests``)
     12    * Contrib apps (``django/contrib/<contribapp>/tests``, see below)
     13
     14We appreciate any and all contributions to the test suite!
     15
     16The Django tests all use the testing infrastructure that ships with Django for
     17testing applications. See :doc:`Testing Django applications </topics/testing>`
     18for an explanation of how to write new tests.
     19
     20.. _running-unit-tests:
     21
     22Running the unit tests
     23----------------------
     24
     25Quickstart
     26~~~~~~~~~~
     27
     28Running the tests requires a Django settings module that defines the
     29databases to use. To make it easy to get started. Django provides a
     30sample settings module that uses the SQLite database. To run the tests
     31with this sample ``settings`` module, ``cd`` into the Django
     32``tests/`` directory and run:
     33
     34.. code-block:: bash
     35
     36    ./runtests.py --settings=test_sqlite
     37
     38If you get an ``ImportError: No module named django.contrib`` error,
     39you need to add your install of Django to your ``PYTHONPATH``. For
     40more details on how to do this, read
     41:ref:`pointing-python-at-the-new-django-version`.
     42
     43Using another ``settings`` module
     44~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     45
     46The included settings module allows you to run the test suite using
     47SQLite. If you want to test behavior using a different database (and
     48if you're proposing patches for Django, it's a good idea to test
     49across databases), you may need to define your own settings file.
     50
     51To run the tests with different settings, ``cd`` to the ``tests/`` directory
     52and type:
     53
     54.. code-block:: bash
     55
     56    ./runtests.py --settings=path.to.django.settings
     57
     58The :setting:`DATABASES` setting in this test settings module needs to define
     59two databases:
     60
     61    * A ``default`` database. This database should use the backend that
     62      you want to use for primary testing
     63
     64    * A database with the alias ``other``. The ``other`` database is
     65      used to establish that queries can be directed to different
     66      databases. As a result, this database can use any backend you
     67      want. It doesn't need to use the same backend as the ``default``
     68      database (although it can use the same backend if you want to).
     69
     70If you're using a backend that isn't SQLite, you will need to provide other
     71details for each database:
     72
     73    * The :setting:`USER` option for each of your databases needs to
     74      specify an existing user account for the database.
     75
     76    * The :setting:`PASSWORD` option needs to provide the password for
     77      the :setting:`USER` that has been specified.
     78
     79    * The :setting:`NAME` option must be the name of an existing database to
     80      which the given user has permission to connect. The unit tests will not
     81      touch this database; the test runner creates a new database whose name is
     82      :setting:`NAME` prefixed with ``test_``, and this test database is
     83      deleted when the tests are finished. This means your user account needs
     84      permission to execute ``CREATE DATABASE``.
     85
     86You will also need to ensure that your database uses UTF-8 as the default
     87character set. If your database server doesn't use UTF-8 as a default charset,
     88you will need to include a value for ``TEST_CHARSET`` in the settings
     89dictionary for the applicable database.
     90
     91Running only some of the tests
     92~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     93
     94Django's entire test suite takes a while to run, and running every single test
     95could be redundant if, say, you just added a test to Django that you want to
     96run quickly without running everything else. You can run a subset of the unit
     97tests by appending the names of the test modules to ``runtests.py`` on the
     98command line.
     99
     100For example, if you'd like to run tests only for generic relations and
     101internationalization, type:
     102
     103.. code-block:: bash
     104
     105    ./runtests.py --settings=path.to.settings generic_relations i18n
     106
     107How do you find out the names of individual tests? Look in ``tests/modeltests``
     108and ``tests/regressiontests`` -- each directory name there is the name of a
     109test.
     110
     111If you just want to run a particular class of tests, you can specify a list of
     112paths to individual test classes. For example, to run the ``TranslationTests``
     113of the ``i18n`` module, type:
     114
     115.. code-block:: bash
     116
     117    ./runtests.py --settings=path.to.settings i18n.TranslationTests
     118
     119Going beyond that, you can specify an individual test method like this:
     120
     121.. code-block:: bash
     122
     123    ./runtests.py --settings=path.to.settings i18n.TranslationTests.test_lazy_objects
     124
     125Running all the tests
     126~~~~~~~~~~~~~~~~~~~~~
     127
     128If you want to run the full suite of tests, you'll need to install a number of
     129dependencies:
     130
     131    *  PyYAML_
     132    *  Markdown_
     133    *  Textile_
     134    *  Docutils_
     135    *  setuptools_
     136    *  memcached_, plus a :ref:`supported Python binding <memcached>`
     137    *  gettext_ (:ref:`gettext_on_windows`)
     138
     139If you want to test the memcached cache backend, you'll also need to define
     140a :setting:`CACHES` setting that points at your memcached instance.
     141
     142Each of these dependencies is optional. If you're missing any of them, the
     143associated tests will be skipped.
     144
     145.. _PyYAML: http://pyyaml.org/wiki/PyYAML
     146.. _Markdown: http://pypi.python.org/pypi/Markdown/1.7
     147.. _Textile: http://pypi.python.org/pypi/textile
     148.. _docutils: http://pypi.python.org/pypi/docutils/0.4
     149.. _setuptools: http://pypi.python.org/pypi/setuptools/
     150.. _memcached: http://www.danga.com/memcached/
     151.. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
     152
     153Contrib apps
     154------------
     155
     156Tests for apps in ``django/contrib/`` go in their respective directories under
     157``django/contrib/``, in a ``tests.py`` file. (You can split the tests over
     158multiple modules by using a ``tests`` directory in the normal Python way.)
     159
     160For the tests to be found, a ``models.py`` file must exist (it doesn't
     161have to have anything in it). If you have URLs that need to be
     162mapped, put them in ``tests/urls.py``.
     163
     164To run tests for just one contrib app (e.g. ``markup``), use the same
     165method as above::
     166
     167    ./runtests.py --settings=settings markup

  • new file docs/internals/contributing/writing-documentation.txt 

    diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt
new file mode 100644
index 0000000..9e86442
    - +  
     1=====================
     2Writing documentation
     3=====================
     4
     5We place a high importance on consistency and readability of documentation.
     6After all, Django was created in a journalism environment! So we treat our
     7documentation like we treat our code: we aim to improve it as often as
     8possible.
     9
     10Documentation changes generally come in two forms:
     11
     12    * General improvements -- Typo corrections, error fixes and better
     13      explanations through clearer writing and more examples.
     14
     15    * New features -- Documentation of features that have been added to the
     16      framework since the last release.
     17
     18This section explains how writers can craft their documentation changes in the
     19most useful and least error-prone ways.
     20
     21Getting started with Sphinx
     22---------------------------
     23
     24Django's documentation uses the Sphinx__ documentation system, which in turn is
     25based on docutils__. The basic idea is that lightly-formatted plain-text
     26documentation is transformed into HTML, PDF, and any other output format.
     27
     28__ http://sphinx.pocoo.org/
     29__ http://docutils.sourceforge.net/
     30
     31To actually build the documentation locally, you'll currently need to install
     32Sphinx -- ``easy_install Sphinx`` should do the trick.
     33
     34.. note::
     35
     36    Building the Django documentation requires Sphinx 1.0.2 or newer. Sphinx
     37    also requires the Pygments__ library for syntax highlighting; building the
     38    Django documentation requires Pygments 1.1 or newer (a new-enough version
     39    should automatically be installed along with Sphinx).
     40
     41__ http://pygments.org
     42
     43Then, building the HTML is easy; just ``make html`` from the ``docs``
     44directory.
     45
     46To get started contributing, you'll want to read the `reStructuredText
     47Primer`__. After that, you'll want to read about the `Sphinx-specific markup`__
     48that's used to manage metadata, indexing, and cross-references.
     49
     50__ http://sphinx.pocoo.org/rest.html
     51__ http://sphinx.pocoo.org/markup/
     52
     53Commonly used terms
     54-------------------
     55
     56Here are some style guidelines on commonly used terms throughout the
     57documentation:
     58
     59    * **Django** -- when referring to the framework, capitalize Django. It is
     60      lowercase only in Python code and in the djangoproject.com logo.
     61
     62    * **email** -- no hyphen.
     63
     64    * **MySQL**
     65
     66    * **PostgreSQL**
     67
     68    * **Python** -- when referring to the language, capitalize Python.
     69
     70    * **realize**, **customize**, **initialize**, etc. -- use the American
     71      "ize" suffix, not "ise."
     72
     73    * **SQLite**
     74
     75    * **subclass** -- it's a single word without a hyphen, both as a verb
     76      ("subclass that model") and as a noun ("create a subclass").
     77
     78    * **Web**, **World Wide Web**, **the Web** -- note Web is always
     79      capitalized when referring to the World Wide Web.
     80
     81    * **Web site** -- use two words, with Web capitalized.
     82
     83Django-specific terminology
     84---------------------------
     85
     86    * **model** -- it's not capitalized.
     87
     88    * **template** -- it's not capitalized.
     89
     90    * **URLconf** -- use three capitalized letters, with no space before
     91      "conf."
     92
     93    * **view** -- it's not capitalized.
     94
     95Guidelines for reStructuredText files
     96-------------------------------------
     97
     98These guidelines regulate the format of our reST (reStructuredText)
     99documentation:
     100
     101    * In section titles, capitalize only initial words and proper nouns.
     102
     103    * Wrap the documentation at 80 characters wide, unless a code example
     104      is significantly less readable when split over two lines, or for another
     105      good reason.
     106     
     107    * The main thing to keep in mind as you write and edit docs is that the
     108      more semantic markup you can add the better. So::
     109
     110          Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
     111
     112      Isn't nearly as helpful as::
     113
     114          Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
     115
     116      This is because Sphinx will generate proper links for the latter, which
     117      greatly helps readers. There's basically no limit to the amount of useful
     118      markup you can add.
     119
     120Django-specific markup
     121----------------------
     122
     123Besides the `Sphinx built-in markup`__, Django's docs defines some extra
     124description units:
     125
     126__ http://sphinx.pocoo.org/markup/desc.html
     127
     128    * Settings::
     129
     130            .. setting:: INSTALLED_APPS
     131
     132      To link to a setting, use ``:setting:`INSTALLED_APPS```.
     133
     134    * Template tags::
     135
     136            .. templatetag:: regroup
     137
     138      To link, use ``:ttag:`regroup```.
     139
     140    * Template filters::
     141
     142            .. templatefilter:: linebreaksbr
     143
     144      To link, use ``:tfilter:`linebreaksbr```.
     145
     146    * Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``)::
     147
     148            .. fieldlookup:: exact
     149
     150      To link, use ``:lookup:`exact```.
     151
     152    * ``django-admin`` commands::
     153
     154            .. django-admin:: syncdb
     155
     156      To link, use ``:djadmin:`syncdb```.
     157
     158    * ``django-admin`` command-line options::
     159
     160            .. django-admin-option:: --traceback
     161
     162      To link, use ``:djadminopt:`--traceback```.
     163
     164.. _documenting-new-features:
     165
     166Documenting new features
     167------------------------
     168
     169Our policy for new features is:
     170
     171    **All documentation of new features should be written in a way that clearly
     172    designates the features are only available in the Django development
     173    version. Assume documentation readers are using the latest release, not the
     174    development version.**
     175
     176Our preferred way for marking new features is by prefacing the features'
     177documentation with: "``.. versionadded:: X.Y``", followed by an optional one
     178line comment and a mandatory blank line.
     179
     180General improvements, or other changes to the APIs that should be emphasized
     181should use the "``.. versionchanged:: X.Y``" directive (with the same format as
     182the ``versionadded`` mentioned above.
     183
     184An example
     185----------
     186
     187For a quick example of how it all fits together, consider this hypothetical
     188example:
     189
     190    * First, the ``ref/settings.txt`` document could have an overall layout
     191      like this:
     192
     193      .. code-block:: rst
     194
     195        ========
     196        Settings
     197        ========
     198
     199        ...
     200
     201        .. _available-settings:
     202
     203        Available settings
     204        ==================
     205
     206        ...
     207
     208        .. _deprecated-settings:
     209
     210        Deprecated settings
     211        ===================
     212
     213        ...
     214
     215    * Next, the ``topics/settings.txt`` document could contain something like
     216      this:
     217
     218      .. code-block:: rst
     219
     220        You can access a :ref:`listing of all available settings
     221        <available-settings>`. For a list of deprecated settings see
     222        :ref:`deprecated-settings`.
     223
     224        You can find both in the :doc:`settings reference document
     225        </ref/settings>`.
     226
     227      We use the Sphinx doc_ cross reference element when we want to link to
     228      another document as a whole and the ref_ element when we want to link to
     229      an arbitrary location in a document.
     230
     231.. _doc: http://sphinx.pocoo.org/markup/inline.html#role-doc
     232.. _ref: http://sphinx.pocoo.org/markup/inline.html#role-ref
     233
     234    * Next, notice how the settings are annotated:
     235
     236      .. code-block:: rst
     237
     238        .. setting:: ADMIN_FOR
     239
     240        ADMIN_FOR
     241        ---------
     242
     243        Default: ``()`` (Empty tuple)
     244
     245        Used for admin-site settings modules, this should be a tuple of
     246        settings modules (in the format ``'foo.bar.baz'``) for which this site
     247        is an admin.
     248
     249        The admin site uses this in its automatically-introspected
     250        documentation of models, views and template tags.
     251
     252      This marks up the following header as the "canonical" target for the
     253      setting ``ADMIN_FOR`` This means any time I talk about ``ADMIN_FOR``, I
     254      can reference it using ``:setting:`ADMIN_FOR```.
     255
     256That's basically how everything fits together.
     257
     258.. _improving-the-documentation:
     259
     260Improving the documentation
     261---------------------------
     262
     263A few small improvements can be made to make the documentation read and
     264look better:
     265
     266    * Most of the various ``index.txt`` documents have *very* short or even
     267      non-existent intro text. Each of those documents needs a good short intro
     268      the content below that point.
     269
     270    * The glossary is very perfunctory. It needs to be filled out.
     271
     272    * Add more metadata targets. Lots of places look like::
     273
     274            ``File.close()``
     275            ~~~~~~~~~~~~~~~~
     276
     277      \... these should be::
     278
     279            .. method:: File.close()
     280
     281      That is, use metadata instead of titles.
     282
     283    * Add more links -- nearly everything that's an inline code literal
     284      right now can probably be turned into a xref.
     285
     286      See the ``literals_to_xrefs.py`` file in ``_ext`` -- it's a shell script
     287      to help do this work.
     288
     289      This will probably be a continuing, never-ending project.
     290
     291    * Add `info field lists`__ where appropriate.
     292
     293      __ http://sphinx.pocoo.org/markup/desc.html#info-field-lists
     294
     295    * Whenever possible, use links. So, use ``:setting:`ADMIN_FOR``` instead of
     296      ````ADMIN_FOR````.
     297
     298    * Use directives where appropriate. Some directives
     299      (e.g. ``.. setting::``) are prefix-style directives; they go *before*
     300      the unit they're describing. These are known as "crossref" directives.
     301      Others (e.g. ``.. class::``) generate their own markup; these should go
     302      inside the section they're describing. These are called
     303      "description units".
     304
     305      You can tell which are which by looking at in :file:`_ext/djangodocs.py`;
     306      it registers roles as one of the other.
     307
     308    * Add ``.. code-block:: <lang>`` to literal blocks so that they get
     309      highlighted.
     310
     311    * When referring to classes/functions/modules, etc., you'll want to use the
     312      fully-qualified name of the target
     313      (``:class:`django.contrib.contenttypes.models.ContentType```).
     314
     315      Since this doesn't look all that awesome in the output -- it shows the
     316      entire path to the object -- you can prefix the target with a ``~``
     317      (that's a tilde) to get just the "last bit" of that path. So
     318      ``:class:`~django.contrib.contenttypes.models.ContentType``` will just
     319      display a link with the title "ContentType".

  • deleted file docs/internals/documentation.txt 

    diff --git a/docs/internals/documentation.txt b/docs/internals/documentation.txt
deleted file mode 100644
index a0dd17f..0000000
    + -  
    1 How the Django documentation works
    2 ==================================
    3 
    4 \... and how to contribute.
    5 
    6 Django's documentation uses the Sphinx__ documentation system, which in turn is
    7 based on docutils__. The basic idea is that lightly-formatted plain-text
    8 documentation is transformed into HTML, PDF, and any other output format.
    9 
    10 __ http://sphinx.pocoo.org/
    11 __ http://docutils.sourceforge.net/
    12 
    13 To actually build the documentation locally, you'll currently need to install
    14 Sphinx -- ``easy_install Sphinx`` should do the trick.
    15 
    16 .. note::
    17 
    18     Building the Django documentation requires Sphinx 1.0.2 or newer. Sphinx
    19     also requires the Pygments__ library for syntax highlighting; building the
    20     Django documentation requires Pygments 1.1 or newer (a new-enough version
    21     should automatically be installed along with Sphinx).
    22 
    23 __ http://pygments.org
    24 
    25 Then, building the HTML is easy; just ``make html`` from the ``docs`` directory.
    26 
    27 To get started contributing, you'll want to read the `reStructuredText
    28 Primer`__. After that, you'll want to read about the `Sphinx-specific markup`__
    29 that's used to manage metadata, indexing, and cross-references.
    30 
    31 __ http://sphinx.pocoo.org/rest.html
    32 __ http://sphinx.pocoo.org/markup/
    33 
    34 The main thing to keep in mind as you write and edit docs is that the more
    35 semantic markup you can add the better. So::
    36 
    37     Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
    38 
    39 Isn't nearly as helpful as::
    40 
    41     Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
    42 
    43 This is because Sphinx will generate proper links for the latter, which greatly
    44 helps readers. There's basically no limit to the amount of useful markup you can
    45 add.
    46 
    47 Django-specific markup
    48 ----------------------
    49 
    50 Besides the `Sphinx built-in markup`__, Django's docs defines some extra description units:
    51 
    52 __ http://sphinx.pocoo.org/markup/desc.html
    53 
    54     * Settings::
    55 
    56             .. setting:: INSTALLED_APPS
    57 
    58       To link to a setting, use ``:setting:`INSTALLED_APPS```.
    59 
    60     * Template tags::
    61 
    62             .. templatetag:: regroup
    63 
    64       To link, use ``:ttag:`regroup```.
    65 
    66     * Template filters::
    67 
    68             .. templatefilter:: linebreaksbr
    69 
    70       To link, use ``:tfilter:`linebreaksbr```.
    71 
    72     * Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``)::
    73 
    74             .. fieldlookup:: exact
    75 
    76       To link, use ``:lookup:`exact```.
    77 
    78     * ``django-admin`` commands::
    79 
    80             .. django-admin:: syncdb
    81 
    82       To link, use ``:djadmin:`syncdb```.
    83 
    84     * ``django-admin`` command-line options::
    85 
    86             .. django-admin-option:: --traceback
    87 
    88       To link, use ``:djadminopt:`--traceback```.
    89 
    90 An example
    91 ----------
    92 
    93 For a quick example of how it all fits together, consider this hypothetical
    94 example:
    95 
    96     * First, the ``ref/settings.txt`` document could have an overall layout
    97       like this:
    98 
    99       .. code-block:: rst
    100 
    101         ========
    102         Settings
    103         ========
    104 
    105         ...
    106 
    107         .. _available-settings:
    108 
    109         Available settings
    110         ==================
    111 
    112         ...
    113 
    114         .. _deprecated-settings:
    115 
    116         Deprecated settings
    117         ===================
    118 
    119         ...
    120 
    121     * Next, the ``topics/settings.txt`` document could contain something like
    122       this:
    123 
    124       .. code-block:: rst
    125 
    126         You can access a :ref:`listing of all available settings
    127         <available-settings>`. For a list of deprecated settings see
    128         :ref:`deprecated-settings`.
    129 
    130         You can find both in the :doc:`settings reference document </ref/settings>`.
    131 
    132       We use the Sphinx doc_ cross reference element when we want to link to
    133       another document as a whole and the ref_ element when we want to link to
    134       an arbitrary location in a document.
    135 
    136 .. _doc: http://sphinx.pocoo.org/markup/inline.html#role-doc
    137 .. _ref: http://sphinx.pocoo.org/markup/inline.html#role-ref
    138 
    139     * Next, notice how the settings are annotated:
    140 
    141       .. code-block:: rst
    142 
    143         .. setting:: ADMIN_FOR
    144 
    145         ADMIN_FOR
    146         ---------
    147 
    148         Default: ``()`` (Empty tuple)
    149 
    150         Used for admin-site settings modules, this should be a tuple of settings
    151         modules (in the format ``'foo.bar.baz'``) for which this site is an
    152         admin.
    153 
    154         The admin site uses this in its automatically-introspected
    155         documentation of models, views and template tags.
    156 
    157       This marks up the following header as the "canonical" target for the
    158       setting ``ADMIN_FOR`` This means any time I talk about ``ADMIN_FOR``, I
    159       can reference it using ``:setting:`ADMIN_FOR```.
    160 
    161 That's basically how everything fits together.
    162 
    163 TODO
    164 ----
    165 
    166 The work is mostly done, but here's what's left, in rough order of priority.
    167 
    168     * Most of the various ``index.txt`` documents have *very* short or even
    169       non-existent intro text. Each of those documents needs a good short intro
    170       the content below that point.
    171 
    172     * The glossary is very perfunctory. It needs to be filled out.
    173 
    174     * Add more metadata targets: there's lots of places that look like::
    175 
    176             ``File.close()``
    177             ~~~~~~~~~~~~~~~~
    178 
    179       \... these should be::
    180 
    181             .. method:: File.close()
    182 
    183       That is, use metadata instead of titles.
    184 
    185     * Add more links -- nearly everything that's an inline code literal
    186       right now can probably be turned into a xref.
    187 
    188       See the ``literals_to_xrefs.py`` file in ``_ext`` -- it's a shell script
    189       to help do this work.
    190 
    191       This will probably be a continuing, never-ending project.
    192 
    193     * Add `info field lists`__ where appropriate.
    194 
    195       __ http://sphinx.pocoo.org/markup/desc.html#info-field-lists
    196 
    197     * Add ``.. code-block:: <lang>`` to literal blocks so that they get
    198       highlighted.
    199 
    200 Hints
    201 -----
    202 
    203 Some hints for making things look/read better:
    204 
    205     * Whenever possible, use links. So, use ``:setting:`ADMIN_FOR``` instead of
    206       ````ADMIN_FOR````.
    207 
    208     * Some directives (``.. setting::``, for one) are prefix-style directives;
    209       they go *before* the unit they're describing. These are known as
    210       "crossref" directives. Others (``.. class::``, e.g.) generate their own
    211       markup; these should go inside the section they're describing. These are
    212       called "description units".
    213 
    214       You can tell which are which by looking at in :file:`_ext/djangodocs.py`;
    215       it registers roles as one of the other.
    216 
    217     * When referring to classes/functions/modules, etc., you'll want to use the
    218       fully-qualified name of the target
    219       (``:class:`django.contrib.contenttypes.models.ContentType```).
    220 
    221       Since this doesn't look all that awesome in the output -- it shows the
    222       entire path to the object -- you can prefix the target with a ``~``
    223       (that's a tilde) to get just the "last bit" of that path. So
    224       ``:class:`~django.contrib.contenttypes.models.ContentType``` will just
    225       display a link with the title "ContentType".

  • docs/internals/index.txt 

    diff --git a/docs/internals/index.txt b/docs/internals/index.txt
index 26c941a..991236b 100644
    a b the hood".  
    1414    these internals if we must.
    1515
    1616.. toctree::
    17    :maxdepth: 1
     17   :maxdepth: 2
    1818
    19    contributing
    20    documentation
     19   contributing/index
    2120   committers
    2221   release-process
    2322   deprecation
Back to Top