diff --git a/docs/internals/contributing/new-contributors.txt b/docs/internals/contributing/new-contributors.txt index 8e81031b324..c728abccd6c 100644 --- a/docs/internals/contributing/new-contributors.txt +++ b/docs/internals/contributing/new-contributors.txt @@ -21,53 +21,55 @@ First steps Start with these steps to discover Django's development process. -* **Triage tickets** +Triage tickets +-------------- - If an `unreviewed ticket`_ reports a bug, try and reproduce it. If you - can reproduce 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. See more at - :ref:`how-can-i-help-with-triaging` +If an `unreviewed ticket`_ reports a bug, try and reproduce it. If you can +reproduce 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. See more at :ref:`how-can-i-help-with-triaging` -* **Look for tickets that are accepted and review patches to build familiarity - with the codebase and the process** +Review patches of accepted tickets +---------------------------------- - 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. :doc:`Run the tests - ` and make sure they pass. - Where possible and relevant, try them out on a database other than SQLite. - Leave comments and feedback! +This will help you build familiarity with the codebase and processes. 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. :doc:`Run the tests +` and make sure they pass. +Where possible and relevant, try them out on a database other than SQLite. +Leave comments and feedback! -* **Keep old patches up to date** +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. Updating a patch is both useful and important! See more on - :doc:`writing-code/submitting-patches`. +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. Updating a patch is both useful and important! See more on +:doc:`writing-code/submitting-patches`. -* **Write some documentation** +Write some documentation +------------------------ - Django's documentation is great but it can always be improved. Did you find - a typo? Do you think that something should be clarified? Go ahead and - suggest a documentation patch! See also the guide on - :doc:`writing-documentation`. +Django's documentation is great but it can always be improved. Did you find a +typo? Do you think that something should be clarified? Go ahead and suggest a +documentation patch! See also the guide on :doc:`writing-documentation`. - .. note:: +.. 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. + 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: https://code.djangoproject.com/wiki/Reports + .. _reports page: https://code.djangoproject.com/wiki/Reports -* **Sign the Contributor License Agreement** +Sign the Contributor License Agreement +-------------------------------------- - The code that you write belongs to you or your employer. If your - contribution is more than one or two lines of code, you need to sign the - `CLA`_. See the `Contributor License Agreement FAQ`_ for a more thorough - explanation. +The code that you write belongs to you or your employer. If your contribution +is more than one or two lines of code, you need to sign the `CLA`_. See the +`Contributor License Agreement FAQ`_ for a more thorough explanation. .. _CLA: https://www.djangoproject.com/foundation/cla/ .. _Contributor License Agreement FAQ: https://www.djangoproject.com/foundation/cla/faq/ @@ -80,78 +82,86 @@ Guidelines As a newcomer on a large project, it's easy to experience frustration. Here's some advice to make your work on Django more useful and rewarding. -* **Pick a subject area that you care about, that you are familiar with, or - that you want to learn about** +Pick a subject area +------------------- - 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. +This should be something 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. -* **Analyze tickets' context and history** +Analyze tickets' context and history +------------------------------------ - 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 an experienced contributor hasn't been - recently involved in a discussion, then a ticket may not have the support - required to get into Django. +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 an experienced contributor hasn't been recently involved in +a discussion, then a ticket may not have the support required to get into +Django. -* **Start small** +Start small +----------- - It's easier to get feedback on a little issue than on a big one. See the - `easy pickings`_. +It's easier to get feedback on a little issue than on a big one. See the +`easy pickings`_. -* **If you're going to engage in a big task, make sure that your idea has - support first** +Confirm support before engaging in a big task +--------------------------------------------- - This means getting someone else to confirm that a bug is real before you fix - the issue, and ensuring that there's consensus on a proposed feature before - you go implementing it. +This means getting someone else to confirm that a bug is real before you fix +the issue, and ensuring that there's consensus on a proposed feature before you +go implementing it. -* **Be bold! Leave feedback!** +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 any one person. We can't - do it without **you**! +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 any one person. We can't do +it without **you**! -* **Err on the side of caution when marking things Ready For Check-in** +Be cautious 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. +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** +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. +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** +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. +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. -* **Be patient** +Be patient +---------- - It's not always easy for your ticket or your patch to be reviewed quickly. - This isn't personal. There are a lot of tickets and pull requests to get - through. +It's not always easy for your ticket or your patch to be reviewed quickly. This +isn't personal. There are a lot of tickets and pull requests to get through. - Keeping your patch up to date is important. Review the ticket on Trac to - ensure that the *Needs tests*, *Needs documentation*, and *Patch needs - improvement* flags are unchecked once you've addressed all review comments. +Keeping your patch up to date is important. Review the ticket on Trac to ensure +that the *Needs tests*, *Needs documentation*, and *Patch needs improvement* +flags are unchecked once you've addressed all review comments. - Remember that Django has an eight-month release cycle, so there's plenty of - time for your patch to be reviewed. +Remember that Django has an eight-month release cycle, so there's plenty of +time for your patch to be reviewed. - Finally, a well-timed reminder can help. See :ref:`contributing code FAQ - ` for ideas here. +Finally, a well-timed reminder can help. See :ref:`contributing code FAQ +` for ideas here. .. _easy pickings: https://code.djangoproject.com/query?status=!closed&easy=1