mirror of https://github.com/django/django.git
Fixed #35863 -- Replaced bold text with heading level 3 in new contributors docs.
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
Sarah Boyce
parent
c2c544cf01
commit
c4c076223e
|
|
@ -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
|
||||
</internals/contributing/writing-code/unit-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
|
||||
</internals/contributing/writing-code/unit-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
|
||||
<new-contributors-faq>` for ideas here.
|
||||
Finally, a well-timed reminder can help. See :ref:`contributing code FAQ
|
||||
<new-contributors-faq>` for ideas here.
|
||||
|
||||
.. _easy pickings: https://code.djangoproject.com/query?status=!closed&easy=1
|
||||
|
|
|
|||
Loading…
Reference in New Issue