From 69af5573c39b10e287ba3a341b1e194c9a0c344e Mon Sep 17 00:00:00 2001 From: Gabriel Hurley Date: Fri, 25 Feb 2011 02:51:16 +0000 Subject: [PATCH] [1.2.X] Fixed #14401 -- Added a contributing howto guide for new users. Thank you to everyone who added their advice, feedback, and wisdom to the wiki article while constructing this new guide. Backport of [15645] from trunk. git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@15646 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/howto/contribute.txt | 286 ++++++++++++++++++++++++++++++++ docs/howto/index.txt | 1 + docs/internals/contributing.txt | 126 +++++++------- 3 files changed, 355 insertions(+), 58 deletions(-) create mode 100644 docs/howto/contribute.txt diff --git a/docs/howto/contribute.txt b/docs/howto/contribute.txt new file mode 100644 index 0000000000..eb1dd105cc --- /dev/null +++ b/docs/howto/contribute.txt @@ -0,0 +1,286 @@ +=========================== +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. diff --git a/docs/howto/index.txt b/docs/howto/index.txt index 49d0644034..7ce7d26ceb 100644 --- a/docs/howto/index.txt +++ b/docs/howto/index.txt @@ -11,6 +11,7 @@ you quickly accomplish common tasks. apache-auth auth-remote-user + contribute custom-management-commands custom-model-fields custom-template-tags diff --git a/docs/internals/contributing.txt b/docs/internals/contributing.txt index 4ce6393181..31774b4bdc 100644 --- a/docs/internals/contributing.txt +++ b/docs/internals/contributing.txt @@ -158,11 +158,9 @@ Once you've claimed a ticket, you have a responsibility to work on that ticket 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 @@ -185,20 +183,21 @@ Patch style * 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. @@ -209,11 +208,12 @@ Patch style * 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 ------------------- @@ -233,8 +233,8 @@ the `required details`_. A number of tickets have patches, but those 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. @@ -248,15 +248,18 @@ Since a picture is worth a thousand words, let's start there: :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 + `, and anyone can triage tickets. + Django is a community project, and we encourage `triage by the + community`_. Second, note the five triage stages: @@ -279,22 +282,22 @@ 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 @@ -303,12 +306,13 @@ ticket has or needs in order to be "ready for checkin": "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" @@ -321,8 +325,10 @@ A ticket can be resolved in a number of ways: "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 @@ -334,27 +340,29 @@ A ticket can be resolved in a number of ways: 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. @@ -363,15 +371,15 @@ members can do to help the triage process. In particular, you can help out by: 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: @@ -380,17 +388,19 @@ 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: