Changes between Version 15 and Version 16 of ContributingHowTo


Ignore:
Timestamp:
02/02/2011 04:03:12 PM (5 years ago)
Author:
gabrielhurley
Comment:

Added a draft introduction, went through for significant cleanup/consistency improvements

Legend:

Unmodified
Added
Removed
Modified
  • ContributingHowTo

    v15 v16  
    11== Contributing !HowTo ==
    22
    3 This page is a place to gather information about "the spirit of contributing to Django", how to interpret the various (confusing) stages and flags in Trac, and friendly tips on how new contributors can get started. This information will eventually be compiled into a patch and merged into a permanent home in the Django Docs.
    4 
    5 The topic comes up regularly on the Django Developers mailing list, and people have offered lots of good information in the past. Contributions and improvements are encouraged.
    6 
    7 This is *not* a place for suggestions on how the current process could be improved, or ways that Trac could be better. Let's stick to what *is* for now... ;-)
    8 
    9 A couple useful threads for mining on Django Developers:
    10 
    11  * http://groups.google.com/group/django-developers/browse_frm/thread/97cbdee3954a8f8d/c07562d8a9dd74dc
    12  * http://groups.google.com/group/django-developers/browse_frm/thread/a60a582d1e0a562b/cdcd277444023062
    13  * http://groups.google.com/group/django-developers/browse_frm/thread/a8f3bb8ce8c0d30f/754c64c3f13201f8
    14  * http://groups.google.com/group/django-developers/browse_frm/thread/38d9ac731e161ec6/5392fc2481fd703c
    15  * http://groups.google.com/group/django-developers/browse_frm/thread/57c3c8eea4d73754/cf0df6744e51ed4d
    16  * http://groups.google.com/group/django-developers/msg/7d5144c8db0e58f7
    17  * http://groups.google.com/group/django-developers/browse_frm/thread/b6d007ee842bde04
    18 
    19 And a couple items that were mentioned that would be nice:
    20 
    21  * Alex mentioned possibly doing a screencast on "how to contribute to Django"
    22  * There was a suggestion to have a "how to contribute" step-by-step tutorial with examples of both good and bad tickets.
     3Django 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.
    234
    245=== "The Spirit of Contributing" ===
    256
    26 Trac is a community-tended garden of the bugs people have found, and the features that people would like to see added. As in any garden, sometimes there are weeds, sometimes there are flowers and vegetables that need picking. We need your help to sort out one from the other.
     7Django 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.
    278
    28 Like all gardens, we can aspire to perfection, but in reality, there's no such thing. In the most pristine garden there will still be snails and insects. In a community garden, there will also be 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, try and keep the problems to a mimimum, and educate those coming into the community so that they can become valuable contributing members of the community.
     9Like 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.
    2910
    30 Similarly, while we aim for Trac to be a perfect representation of the state of progress on Django bugs, we acknowledge that this simply will not happen. By distributing the load of Trac maintenance to the community, we accept that there will be inaccuracies and mistakes made. Trac is "mostly accurate", and we give allowances for the fact that sometimes it will be wrong. We also rely on the community to keep participating, keep tickets as accurate as possible, and raise issues for discussions on mailing lists when there appears to be some confusion or difficulty.
     11Similarly, 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''.
    3112
    32 Django is a community project, and every little contribution helps. We can't do this without YOU!
     13We 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.
     14
     15Django is a community project, and every contribution helps. We can't do this without YOU!
    3316
    3417=== Understanding Trac ===
     
    5740 * '''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.
    5841
    59 '''TODO''': add information about to whom a ticket should be assigned at different points in the workflow.
    60 
    6142Here's an example workflow:
    6243
     
    7354''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.''
    7455
    75  * Pick a subject area you care about/are familiar with/want to learn about. (needs more text)
     56 * 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.
    7657
    77  * Triage Tickets. If a ticket is unaccepted and reports a bug, try and duplicate it. If you can 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 underlying issue.
     58 * 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.
    7859
    79  * 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.
     60 * 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!
    8061
    81  * Keep old patches up to date. Oftentimes the codebase will change between a patch being submitted and the time it gets reviewed. Making sure it still applies cleanly and functions as expected is both useful and important!
     62 * 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!
    8263
    83  * Trac isn't an absolute; the context is just as important as the literal message. When reading Trac, you need to take into account who says things, and when they were said. Support 2 years ago by a core team member 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.
     64 * 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.
    8465
    8566 * Start small. It's easier to get feedback on a little issue than on a big one.
    8667
    87  * If you're going to engage in a big task, you should make sure that your idea has support first. This means getting someone else to confirm that a bug is real before you spend a whole lot of time fixing the issue, and confirming that the core team supports a proposed feature before you spend a whole lot of time implementing it.
     68 * If you're going to engage in a big task, you should 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.
    8869
    89  * Be bold! Sometimes it can be scary to put your opinion out to the world and say "this ticket/patch is good or bad", 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!
     70 * 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!
    9071
    91  * Err on the side of caution. If you're really not certain if a ticket is ready for checking, don't mark is 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.
     72 * 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.
    9273
    93  * Wait for feedback, and respond to feedback that you receive. Don't just barge in and mark 50 tickets RFC in a sitting -- especially if it is your first time contributing. Work on one or two tickets, wait for feedback, respond if necessary, and repeat.
     74 * 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.
    9475
    95  * Be rigorous. When we say "PEP8, 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's an indication that you should be the person to write the very first tests for that feature, not that you get a pass from writing tests altogether.
     76 * Be rigorous. When we say "PEP8, 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.
    9677
    9778=== FAQs ===
     
    10081
    10182 1. This ticket I care about has been ignored for days/weeks/months! What can I do to get it committed?
    102    * First off, it's not personal. Django is entirely developed by volunteers, 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.
     83   * 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.
    10384
    10485 2. I'm sure my ticket is perfect, can I mark it as RFC myself?
     
    10788 3. My ticket has been in DDN forever! What should I do?
    10889   * 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.
    109 
    110  4. My ticket has been in RFC forever! What should I do?
    111    * The Ready For Checkin status is essentially a notice to core committers. They're humans with limited time and lots of demands on that time. They absolutely know to be looking for RFC tickets, and they all try to work through RFC tickets as a matter of priority. As with any other case of "my ticket is being ignored", gently raising awareness on Django Developers or the #django-dev IRC channel are the best ways to move things along. All tickets marked as RFC will be dealt with prior to a release.
Back to Top