[1.2.X] Fixed #14401 -- Added a contributing howto guide for new users. Thank...

===========================

How to contribute to Django

===========================

Django is developed 100% by the community, and the more people that are actively

involved in the code the better Django will be. We recognize that contributing

to Django can be daunting at first and sometimes confusing even to

veterans. While we have our official "Contributing to Django" documentation

which spells out the technical details of triaging tickets and submitting

patches, it leaves a lot of room for interpretation. This guide aims to offer

more general advice on issues such as how to interpret the various stages and

flags in Trac, and how new contributors can get started.

.. seealso::

    This guide is meant to answer the most common questions about

    contributing to Django, however it is no substitute for the

    :doc:`/internals/contributing` reference. Please make sure to

    read that document to understand the specific details

    involved in reporting issues and submitting patches.

.. _the-spirit-of-contributing:

"The Spirit of Contributing"

============================

Django uses Trac_ for managing our progress, and Trac is a community-tended

garden of the bugs people have found and the features people would like to see

added. As in any garden, sometimes there are weeds to be pulled and sometimes

there are flowers and vegetables that need picking. We need your help to sort

out one from the other, and in the end we all benefit together.

Like all gardens, we can aspire to perfection but in reality there's no such

thing. Even in the most pristine garden there are still snails and insects. In a

community garden there are also helpful people who--with the best of

intentions--fertilize the weeds and poison the roses. It's the job of the

community as a whole to self-manage, keep the problems to a minimum, and educate

those coming into the community so that they can become valuable contributing

members.

Similarly, while we aim for Trac to be a perfect representation of the state of

Django's progress, we acknowledge that this simply will not happen. By

distributing the load of Trac maintenance to the community, we accept that there

will be mistakes. Trac is "mostly accurate", and we give allowances for the fact

that sometimes it will be wrong. That's okay. We're perfectionists with

deadlines.

We rely on the community to keep participating, keep tickets as accurate as

possible, and raise issues for discussion on our mailing lists when there is

confusion or disagreement.

Django is a community project, and every contribution helps. We can't do this

without YOU!

.. _Trac: http://code.djangoproject.com/

Understanding Trac

==================

Trac is Django's sole official issue tracker. All known bugs, desired features

and ideas for changes are logged there.

However, Trac can be quite confusing even to veteran contributors.  Having to

look at both flags and triage stages isn't immediately obvious, and the stages

themselves can be misinterpreted.

What Django's triage stages "really mean"

-----------------------------------------

Unreviewed

~~~~~~~~~~

The ticket has not been reviewed by anyone who felt qualified to make a judgment

about whether the ticket contained a valid issue, a viable feature, or ought to

be closed for any of the various reasons.

Accepted

~~~~~~~~

The big grey area! The absolute meaning of "accepted" is that the issue

described in the ticket is valid and is in some stage of being worked on. Beyond

that there are several considerations

* **Accepted + No Flags**

  The ticket is valid, but no one has submitted a patch for it yet. Often this

  means you could safely start writing a patch for it.

* **Accepted + Has Patch**

  The ticket is waiting for people to review the supplied patch. This means

  downloading the patch and trying it out, verifying that it contains tests and

  docs, running the test suite with the included patch, and leaving feedback on

  the ticket.

* **Accepted + Has Patch + (any other flag)**

  This means the ticket has been reviewed, and has been found to need further

  work. "Needs tests" and "Needs documentation" are self-explanatory. "Patch

  needs improvement" will generally be accompanied by a comment on the ticket

  explaining what is needed to improve the code.

Design Decision Needed

~~~~~~~~~~~~~~~~~~~~~~

This stage is for issues which may be contentious, may be backwards

incompatible, or otherwise involve high-level design decisions. These decisions

are generally made by the core committers, however that is not a

requirement. See the FAQ below for "My ticket has been in DDN forever!  What

should I do?"

Ready For Checkin

~~~~~~~~~~~~~~~~~

The ticket was reviewed by any member of the community other than the person who

supplied the patch and found to meet all the requirements for a commit-ready

patch. A core committer now needs to give the patch a final review prior to

being committed. See the FAQ below for "My ticket has been in RFC forever!  What

should I do?"

Someday/Maybe?

~~~~~~~~~~~~~~

Generally only used for vague/high-level features or design ideas. These tickets

are uncommon and overall less useful since they don't describe concrete

actionable issues.

Fixed on a branch

~~~~~~~~~~~~~~~~~

Used to indicate that a ticket is resolved as part of a major body of work that

will eventually be merged to trunk.  Tickets in this stage generally don't need

further work. This may happen in the case of major features/refactors in each

release cycle, or as part of the annual Google Summer of Code efforts.

Example Trac workflow

---------------------

Here we see the life-cycle of an average ticket:

* Alice creates a ticket, and uploads an incomplete patch (no tests, incorrect

  implementation).

* Bob reviews the patch, marks it "Accepted", "needs tests", and "patch needs

  improvement", and leaves a comment telling Alice how the patch could be

  improved.

* Alice updates the patch, adding tests (but not changing the

  implementation). She removes the two flags.

* Charlie reviews the patch and resets the "patch needs improvement" flag with

  another comment about improving the implementation.

* Alice updates the patch, fixing the implementation. She removes the "patch

  needs improvement" flag.

* Daisy reviews the patch, and marks it RFC.

* Jacob reviews the RFC patch, applies it to his checkout, and commits it.

Some tickets require much less feedback than this, but then again some tickets

require much much more.

Advice for new contributors

===========================

New contributor and not sure what to do? Want to help but just don't know how to

get started? This is the section for you.

* **Pick a subject area that you care about, that you are familiar with, or that

  you want to learn about.**

  You don't already have to be an expert on the area you want to work on; you

  become an expert through your ongoing contributions to the code.

* **Triage tickets.**

  If a ticket is unreviewed and reports a bug, try and duplicate it.  If you can

  duplicate it and it seems valid, make a note that you confirmed the bug and

  accept the ticket. Make sure the ticket is filed under the correct component

  area. Consider writing a patch that adds a test for the bug's behavior, even

  if you don't fix the bug itself.

* **Look for tickets that are accepted and review patches to build familiarity

  with the codebase and the process.**

  Mark the appropriate flags if a patch needs docs or tests. Look through the

  changes a patch makes, and keep an eye out for syntax that is incompatible

  with older but still supported versions of Python. Run the tests and make sure

  they pass on your system.  Where possible and relevant, try them out on a

  database other than SQLite. Leave comments and feedback!

* **Keep old patches up to date.**

  Oftentimes the codebase will change between a patch being submitted and the

  time it gets reviewed. Make sure it still applies cleanly and functions as

  expected. Simply updating a patch is both useful and important!

* **Trac isn't an absolute; the context is just as important as the words.**

  When reading Trac, you need to take into account who says things, and when

  they were said. Support for an idea two years ago doesn't necessarily mean

  that the idea will still have support. You also need to pay attention to who

  *hasn't* spoken -- for example, if a core team member hasn't been recently

  involved in a discussion, then a ticket may not have the support required to

  get into trunk.

* **Start small.**

  It's easier to get feedback on a little issue than on a big one.

* **If you're going to engage in a big task, make sure that your idea has

  support first.**

  This means getting someone else to confirm that a bug is real before you fix

  the issue, and ensuring that the core team supports a proposed feature before

  you go implementing it.

* **Be bold! Leave feedback!**

  Sometimes it can be scary to put your opinion out to the world and say "this

  ticket is correct" or "this patch needs work", but it's the only way the

  project moves forward. The contributions of the broad Django community

  ultimately have a much greater impact than that of the core developers. We

  can't do it without YOU!

* **Err on the side of caution when marking things Ready For Check-in.**

  If you're really not certain if a ticket is ready, don't mark it as

  such. Leave a comment instead, letting others know your thoughts.  If you're

  mostly certain, but not completely certain, you might also try asking on IRC

  to see if someone else can confirm your suspicions.

* **Wait for feedback, and respond to feedback that you receive.**

  Focus on one or two tickets, see them through from start to finish, and

  repeat. The shotgun approach of taking on lots of tickets and letting some

  fall by the wayside ends up doing more harm than good.

* **Be rigorous.**

  When we say ":pep:`8`, and must have docs and tests", we mean it. If a patch

  doesn't have docs and tests, there had better be a good reason. Arguments like

  "I couldn't find any existing tests of this feature" don't carry much

  weight--while it may be true, that means you have the extra-important job of

  writing the very first tests for that feature, not that you get a pass from

  writing tests altogether.

.. note::

    The `Reports page`_ contains links to many useful Trac queries, including

    several that are useful for triaging tickets and reviewing patches as

    suggested above.

    .. _Reports page: http://code.djangoproject.com/wiki/Reports

FAQs

====

**This ticket I care about has been ignored for days/weeks/months! What can I do

to get it committed?**

* First off, it's not personal. Django is entirely developed by volunteers (even

  the core devs), and sometimes folks just don't have time. The best thing to do

  is to send a gentle reminder to the Django Developers mailing list asking for

  review on the ticket, or to bring it up in the #django-dev IRC channel.

**I'm sure my ticket is absolutely 100% perfect, can I mark it as RFC myself?**

* Short answer: No. It's always better to get another set of eyes on a

  ticket. If you're having trouble getting that second set of eyes, see question

  1, above.

**My ticket has been in DDN forever! What should I do?**

* Design Decision Needed requires consensus about the right solution.  At the

  very least it needs consensus among the core developers, and ideally it has

  consensus from the community as well. The best way to accomplish this is to

  start a thread on the Django Developers mailing list, and for very complex

  issues to start a wiki page summarizing the problem and the possible

  solutions.

   apache-auth

   auth-remote-user

   contribute

   custom-management-commands

   custom-model-fields

   custom-template-tags

in a reasonably timely fashion. If you don't have time to work on it, either

unclaim it or don't claim it in the first place!

Ticket triagers go through the list of claimed tickets from time to

time, checking whether any progress has been made. If there's no sign of

progress on a particular claimed ticket for a week or two, a triager may ask

you to relinquish the ticket claim so that it's no longer monopolized and

somebody else can claim it.

If there's no sign of progress on a particular claimed ticket for a week or

two, another developer may ask you to relinquish the ticket claim so that it's

no longer monopolized and somebody else can claim it.

If you've claimed a ticket and it's taking a long time (days or weeks) to code,

keep everybody updated by posting comments on the ticket. If you don't provide

    * Make sure your code matches our `coding style`_.

    * Submit patches in the format returned by the ``svn diff`` command.

      An exception is for code changes that are described more clearly in plain

      English than in code. Indentation is the most common example; it's hard to

      read patches when the only difference in code is that it's indented.

      An exception is for code changes that are described more clearly in

      plain English than in code. Indentation is the most common example; it's

      hard to read patches when the only difference in code is that it's

      indented.

      Patches in ``git diff`` format are also acceptable.

    * When creating patches, always run ``svn diff`` from the top-level

      ``trunk`` directory -- i.e., the one that contains ``django``, ``docs``,

      ``tests``, ``AUTHORS``, etc. This makes it easy for other people to apply

      your patches.

      ``tests``, ``AUTHORS``, etc. This makes it easy for other people to

      apply your patches.

    * Attach patches to a ticket in the `ticket tracker`_, using the "attach file"

      button. Please *don't* put the patch in the ticket description or comment

      unless it's a single line patch.

    * Attach patches to a ticket in the `ticket tracker`_, using the "attach

      file" button. Please *don't* put the patch in the ticket description

      or comment unless it's a single line patch.

    * Name the patch file with a ``.diff`` extension; this will let the ticket

      tracker apply correct syntax highlighting, which is quite helpful.

    * The code required to fix a problem or add a feature is an essential part

      of a patch, but it is not the only part. A good patch should also include

      a regression test to validate the behavior that has been fixed (and prevent

      the problem from arising again).

      a regression test to validate the behavior that has been fixed

      (and prevent the problem from arising again).

    * If the code associated with a patch adds a new feature, or modifies behavior

      of an existing feature, the patch should also contain documentation.

    * If the code associated with a patch adds a new feature, or modifies

      behavior of an existing feature, the patch should also contain

      documentation.

Non-trivial patches

-------------------

don't meet all the requirements of a `good patch`_.

One way to help out is to *triage* bugs that have been reported by other

users. A couple of dedicated volunteers work on this regularly, but more help

is always appreciated.

users. The core team--as well as many community members--work on this

regularly, but more help is always appreciated.

Most of the workflow is based around the concept of a ticket's "triage stage".

This stage describes where in its lifetime a given ticket is at any time.

   :width: 590

   :alt: Django's ticket workflow

We've got two official roles here:

We've got two roles in this diagram:

    * Core developers: people with commit access who make the big decisions

      and write the bulk of the code.

    * Core developers: people with commit access who are responsible for

      making the big decisions, writing large portions of the code and

      integrating the contributions of the community.

    * Ticket triagers: trusted community members with a proven history of

      working with the Django community. As a result of this history, they

      have been entrusted by the core developers to make some of the smaller

      decisions about tickets.

    * Ticket triagers: anyone in the Django community who chooses to

      become involved in Django's development process. Our Trac installation

      is :ref:`intentionally left open to the public

      <the-spirit-of-contributing>`, and anyone can triage tickets.

      Django is a community project, and we encourage `triage by the

      community`_.

Second, note the five triage stages:

       adding to the framework if an excellent patch is submitted. These

       tickets are not a high priority.

    5. If a ticket has an associated patch (see below), a triager will review

       the patch. If the patch is complete, it'll be marked as "ready for

       checkin" so that a core developer knows to review and check in the

       patches.

    5. If a ticket has an associated patch (see below), it will be reviewed

       by the community. If the patch is complete, it'll be marked as "ready

       for checkin" so that a core developer knows to review and commit the

       patch.

The second part of this workflow involves a set of flags the describe what the

ticket has or needs in order to be "ready for checkin":

    "Has patch"

        This means the ticket has an associated patch_. These will be

        reviewed by the triage team to see if the patch is "good".

        reviewed to see if the patch is "good".

    "Needs documentation"

        This flag is used for tickets with patches that need associated

        documentation. Complete documentation of features is a prerequisite

        before we can check a fix into the codebase.

        before we can check them into the codebase.

    "Needs tests"

        This flags the patch as needing associated unit tests. Again, this is a

    "Patch needs improvement"

        This flag means that although the ticket *has* a patch, it's not quite

        ready for checkin. This could mean the patch no longer applies

        cleanly, or that the code doesn't live up to our standards.

        cleanly, there is a flaw in the implementation, or that the code

        doesn't meet our standards.

A ticket can be resolved in a number of ways:

    "fixed"

        Used by one of the core developers once a patch has been rolled into

        Used by the core developers once a patch has been rolled into

        Django and the issue is fixed.

    "invalid"

    "wontfix"

        Used when a core developer decides that this request is not

        appropriate for consideration in Django. This is usually chosen after

        discussion in the ``django-developers`` mailing list, and you should

        feel free to join in when it's something you care about.

        discussion in the ``django-developers`` mailing list. Feel free to

        start or join in discussions of "wontfix" tickets on the mailing list,

        but please do not reopen tickets closed as "wontfix" by core

        developers.

    "duplicate"

        Used when another ticket covers the same issue. By closing duplicate

If you believe that the ticket was closed in error -- because you're

still having the issue, or it's popped up somewhere else, or the triagers have

-- made a mistake, please reopen the ticket and tell us why. Please do not

reopen tickets that have been marked as "wontfix" by core developers.

made a mistake -- please reopen the ticket and provide further information.

Please do not reopen tickets that have been marked as "wontfix" by core

developers.

.. _required details: `Reporting bugs`_

.. _good patch: `Patch style`_

.. _triage by the community: `Triage by the general community`_

.. _patch: `Submitting patches`_

Triage by the general community

-------------------------------

Although the core developers and ticket triagers make the big decisions in

the ticket triage process, there's also a lot that general community

members can do to help the triage process. In particular, you can help out by:

Although the core developers make the big decisions in the ticket triage

process, there's a lot that general community members can do to help the

triage process. In particular, you can help out by:

    * Closing "Unreviewed" tickets as "invalid", "worksforme" or "duplicate."

    * Promoting "Unreviewed" tickets to "Design decision needed" if a design

      decision needs to be made, or "Accepted" in case of obvious bugs.

    * Correcting the "Needs tests", "Needs documentation", or "Has patch" flags

      for tickets where they are incorrectly set.

    * Correcting the "Needs tests", "Needs documentation", or "Has patch"

      flags for tickets where they are incorrectly set.

    * Adding the `easy-pickings`_ keyword to tickets that are small and

      relatively straightforward.

      any activity in a long time, it's possible that the problem has been

      fixed but the ticket hasn't yet been closed.

    * Contacting the owners of tickets that have been claimed but have not seen

      any recent activity. If the owner doesn't respond after a week or so,

      remove the owner's claim on the ticket.

    * Contacting the owners of tickets that have been claimed but have not

      seen any recent activity. If the owner doesn't respond after a week

      or so, remove the owner's claim on the ticket.

    * Identifying trends and themes in the tickets. If there a lot of bug reports

      about a particular part of Django, it may indicate we should consider

      refactoring that part of the code. If a trend is emerging, you should

      raise it for discussion (referencing the relevant tickets) on

      `django-developers`_.

    * Identifying trends and themes in the tickets. If there a lot of bug

      reports about a particular part of Django, it may indicate we should

      consider refactoring that part of the code. If a trend is emerging,

      you should raise it for discussion (referencing the relevant tickets)

      on `django-developers`_.

However, we do ask the following of all general community members working in

the ticket database:

      make the final determination of the fate of a ticket, usually after

      consultation with the community.

    * Please **don't** promote tickets to "Ready for checkin" unless they are

      *trivial* changes -- for example, spelling mistakes or broken links in

      documentation.

    * Please **don't** promote your own tickets to "Ready for checkin". You

      may mark other people's tickets which you've reviewed as "Ready for

      checkin", but you should get at minimum one other community member to

      review a patch that you submit.

    * Please **don't** reverse a decision that has been made by a core

      developer. If you disagree with a discussion that has been made,

      developer. If you disagree with a decision that has been made,

      please post a message to `django-developers`_.

    * Please be conservative in your actions. If you're unsure if you should

      be making a change, don't make the change -- leave a comment with your

      concerns on the ticket, or post a message to `django-developers`_.

    * If you're unsure if you should be making a change, don't make the change

      but instead leave a comment with your concerns on the ticket, or

      post a message to `django-developers`_. It's okay to be unsure, but

      your input is still valuable.

.. _contributing-translations: