From c5a6badbfc95d839f5952087ac59f7d1e76ac9a6 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Sun, 27 Feb 2011 23:31:46 +0000 Subject: [PATCH] Converted the new contributions docs to unix line endings. git-svn-id: http://code.djangoproject.com/svn/django/trunk@15667 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/howto/contribute.txt | 642 +++++++++++++++++++------------------- 1 file changed, 321 insertions(+), 321 deletions(-) diff --git a/docs/howto/contribute.txt b/docs/howto/contribute.txt index 286c9282c7..5d17ae69aa 100644 --- a/docs/howto/contribute.txt +++ b/docs/howto/contribute.txt @@ -1,321 +1,321 @@ -=========================== -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. - -.. _triage-stages-explained: - -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. - -.. _closing-tickets: - -Closing Tickets ---------------- - -When a ticket has completed its useful lifecycle, it's time for it to be closed. -Closing a ticket is a big responsibility, though. You have to be sure that -the issue is really resolved, and you need to keep in mind that the reporter -of the ticket may not be happy to have their ticket closed (unless it's fixed, -of course). If you're not certain about closing a ticket, just leave a comment -with your thoughts instead. - -If you do close a ticket, you should always make sure of the following: - - * Be certain that the issue is resolved. - - * Leave a comment explaining the decision to close the ticket. - - * If there is a way they can improve the ticket to reopen it, let them know. - - * If the ticket is a duplicate, reference the original ticket. - - * **Be polite.** No one likes having their ticket closed. It can be - frustrating or even discouraging. The best way to avoid turning people - off from contributing to Django is to be polite and friendly and to offer - suggestions for how they could improve this ticket and other tickets in the - future. - -.. seealso:: - - The :ref:`contributing reference ` contains a - description of each of the available resolutions in Trac. - -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. +=========================== +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. + +.. _triage-stages-explained: + +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. + +.. _closing-tickets: + +Closing Tickets +--------------- + +When a ticket has completed its useful lifecycle, it's time for it to be closed. +Closing a ticket is a big responsibility, though. You have to be sure that +the issue is really resolved, and you need to keep in mind that the reporter +of the ticket may not be happy to have their ticket closed (unless it's fixed, +of course). If you're not certain about closing a ticket, just leave a comment +with your thoughts instead. + +If you do close a ticket, you should always make sure of the following: + + * Be certain that the issue is resolved. + + * Leave a comment explaining the decision to close the ticket. + + * If there is a way they can improve the ticket to reopen it, let them know. + + * If the ticket is a duplicate, reference the original ticket. + + * **Be polite.** No one likes having their ticket closed. It can be + frustrating or even discouraging. The best way to avoid turning people + off from contributing to Django is to be polite and friendly and to offer + suggestions for how they could improve this ticket and other tickets in the + future. + +.. seealso:: + + The :ref:`contributing reference ` contains a + description of each of the available resolutions in Trac. + +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.