mirrors/django
mirrors/django
0
0
Fork 0
mirror of https://github.com/django/django.git synced 2024-11-24 02:47:35 +01:00
Code Issues Releases Wiki Activity

Fixed #35863 -- Replaced bold text with heading level 3 in new contributors docs.

Browse Source 
This improves accessibility for screen reader users, see WCAG SC 1.3.1 Info and Relationships:
https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html
This commit is contained in:
ssanger 2024-11-02 10:52:14 -07:00 committed by Sarah Boyce
parent c2c544cf01
commit c4c076223e
1 changed files with 98 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

186
docs/internals/contributing/new-contributors.txt
View File

@ -21,53 +21,55 @@ First steps
Start with these steps to discover Django's development process. 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 If an `unreviewed ticket`_ reports a bug, try and reproduce it. If you can
can reproduce it and it seems valid, make a note that you confirmed the bug reproduce it and it seems valid, make a note that you confirmed the bug and
and accept the ticket. Make sure the ticket is filed under the correct accept the ticket. Make sure the ticket is filed under the correct component
component area. Consider writing a patch that adds a test for the bug's area. Consider writing a patch that adds a test for the bug's behavior, even if
behavior, even if you don't fix the bug itself. See more at you don't fix the bug itself. See more at :ref:`how-can-i-help-with-triaging`
:ref:`how-can-i-help-with-triaging`
* **Look for tickets that are accepted and review patches to build familiarity Review patches of accepted tickets
with the codebase and the process** ----------------------------------
Mark the appropriate flags if a patch needs docs or tests. Look through the This will help you build familiarity with the codebase and processes. Mark the
changes a patch makes, and keep an eye out for syntax that is incompatible appropriate flags if a patch needs docs or tests. Look through the changes a
with older but still supported versions of Python. :doc:`Run the tests patch makes, and keep an eye out for syntax that is incompatible with older but
</internals/contributing/writing-code/unit-tests>` and make sure they pass. still supported versions of Python. :doc:`Run the tests
Where possible and relevant, try them out on a database other than SQLite. </internals/contributing/writing-code/unit-tests>` and make sure they pass.
Leave comments and feedback! 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 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 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 expected. Updating a patch is both useful and important! See more on
:doc:`writing-code/submitting-patches`. :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 Django's documentation is great but it can always be improved. Did you find a
a typo? Do you think that something should be clarified? Go ahead and typo? Do you think that something should be clarified? Go ahead and suggest a
suggest a documentation patch! See also the guide on documentation patch! See also the guide on :doc:`writing-documentation`.
:doc:`writing-documentation`.
.. note:: .. note::
The `reports page`_ contains links to many useful Trac queries, including The `reports page`_ contains links to many useful Trac queries, including
several that are useful for triaging tickets and reviewing patches as several that are useful for triaging tickets and reviewing patches as
suggested above. 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 The code that you write belongs to you or your employer. If your contribution
contribution is more than one or two lines of code, you need to sign the is more than one or two lines of code, you need to sign the `CLA`_. See the
`CLA`_. See the `Contributor License Agreement FAQ`_ for a more thorough `Contributor License Agreement FAQ`_ for a more thorough explanation.
explanation.
.. _CLA: https://www.djangoproject.com/foundation/cla/ .. _CLA: https://www.djangoproject.com/foundation/cla/
.. _Contributor License Agreement FAQ: https://www.djangoproject.com/foundation/cla/faq/ .. _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 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. 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 Pick a subject area
that you want to learn about** -------------------
You don't already have to be an expert on the area you want to work on; you This should be something that you care about, that you are familiar with or
become an expert through your ongoing contributions to the code. 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. Trac isn't an absolute; the context is just as important as the words. When
When reading Trac, you need to take into account who says things, and when reading Trac, you need to take into account who says things, and when they were
they were said. Support for an idea two years ago doesn't necessarily mean said. Support for an idea two years ago doesn't necessarily mean that the idea
that the idea will still have support. You also need to pay attention to who will still have support. You also need to pay attention to who *hasn't* spoken
*hasn't* spoken -- for example, if an experienced contributor hasn't been -- for example, if an experienced contributor hasn't been recently involved in
recently involved in a discussion, then a ticket may not have the support a discussion, then a ticket may not have the support required to get into
required to get into Django. Django.
* **Start small** Start small
-----------
It's easier to get feedback on a little issue than on a big one. See the It's easier to get feedback on a little issue than on a big one. See the
`easy pickings`_. `easy pickings`_.
* **If you're going to engage in a big task, make sure that your idea has Confirm support before engaging in a big task
support first** ---------------------------------------------
This means getting someone else to confirm that a bug is real before you fix 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 the issue, and ensuring that there's consensus on a proposed feature before you
you go implementing it. 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 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 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 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 ultimately have a much greater impact than that of any one person. We can't do
do it without **you**! 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 If you're really not certain if a ticket is ready, don't mark it as such. Leave
such. Leave a comment instead, letting others know your thoughts. If you're a comment instead, letting others know your thoughts. If you're mostly certain,
mostly certain, but not completely certain, you might also try asking on IRC but not completely certain, you might also try asking on IRC to see if someone
to see if someone else can confirm your suspicions. 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 Focus on one or two tickets, see them through from start to finish, and repeat.
repeat. The shotgun approach of taking on lots of tickets and letting some The shotgun approach of taking on lots of tickets and letting some fall by the
fall by the wayside ends up doing more harm than good. 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 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 doesn't have docs and tests, there had better be a good reason. Arguments like
like "I couldn't find any existing tests of this feature" don't carry much "I couldn't find any existing tests of this feature" don't carry much weight.
weight--while it may be true, that means you have the extra-important job of While it may be true, that means you have the extra-important job of writing
writing the very first tests for that feature, not that you get a pass from the very first tests for that feature, not that you get a pass from writing
writing tests altogether. tests altogether.
* **Be patient** Be patient
----------
It's not always easy for your ticket or your patch to be reviewed quickly. It's not always easy for your ticket or your patch to be reviewed quickly. This
This isn't personal. There are a lot of tickets and pull requests to get isn't personal. There are a lot of tickets and pull requests to get through.
through.
Keeping your patch up to date is important. Review the ticket on Trac to Keeping your patch up to date is important. Review the ticket on Trac to ensure
ensure that the *Needs tests*, *Needs documentation*, and *Patch needs that the *Needs tests*, *Needs documentation*, and *Patch needs improvement*
improvement* flags are unchecked once you've addressed all review comments. flags are unchecked once you've addressed all review comments.
Remember that Django has an eight-month release cycle, so there's plenty of Remember that Django has an eight-month release cycle, so there's plenty of
time for your patch to be reviewed. time for your patch to be reviewed.
Finally, a well-timed reminder can help. See :ref:`contributing code FAQ Finally, a well-timed reminder can help. See :ref:`contributing code FAQ
<new-contributors-faq>` for ideas here. <new-contributors-faq>` for ideas here.
.. _easy pickings: https://code.djangoproject.com/query?status=!closed&easy=1 .. _easy pickings: https://code.djangoproject.com/query?status=!closed&easy=1