Ticket #14401: 14401_contributing_howto.diff

File 14401_contributing_howto.diff, 12.7 KB (added by Gabriel Hurley, 14 years ago)
  • docs/howto/contribute.txt

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

     
    1111
    1212   apache-auth
    1313   auth-remote-user
     14   contribute
    1415   custom-management-commands
    1516   custom-model-fields
    1617   custom-template-tags
  • docs/internals/contributing.txt

     
    3232works and how it handles bugs, mailing lists, and all the other minutiae of
    3333Django development.
    3434
     35.. seealso::
     36
     37    This document contains specific details for contributing to
     38    Django. However, many new contributors find this guide confusing
     39    or intimidating at first. For a simpler introduction
     40    to becoming a contributor please see the :doc:`/howto/contribute` guide.
     41
    3542.. _reporting-bugs:
    3643
    3744Reporting bugs
Back to Top