mirror of
https://github.com/django/django.git
synced 2024-11-29 22:56:46 +01:00
3895d8899d
Added docs/internals/mailing-lists.txt documenting the use of django's mailing lists. All references across docs changed to point to this page. The referencing makes use of substitution because there's no way to make a :ref: link in a non-inline fashion in Sphinx. It also makes use of rst_epilog Sphinx conf for making this substitutions across all the docs.
152 lines
6.1 KiB
Plaintext
152 lines
6.1 KiB
Plaintext
===========================
|
|
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.
|
|
|
|
First steps
|
|
-----------
|
|
|
|
Start with these easy tasks to discover Django's development process.
|
|
|
|
* **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.
|
|
|
|
* **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`
|
|
|
|
* **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! See more on
|
|
:doc:`writing-code/submitting-patches`.
|
|
|
|
* **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`, in particular the tips for
|
|
:ref:`improving-the-documentation`.
|
|
|
|
.. 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: https://code.djangoproject.com/wiki/Reports
|
|
|
|
.. _CLA: https://www.djangoproject.com/foundation/cla/
|
|
.. _Contributor License Agreement FAQ: https://www.djangoproject.com/foundation/cla/faq/
|
|
.. _unreviewed ticket: https://code.djangoproject.com/query?status=!closed&stage=Unreviewed
|
|
|
|
|
|
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**
|
|
|
|
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**
|
|
|
|
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. See the
|
|
`easy pickings`_.
|
|
|
|
* **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.
|
|
|
|
.. _easy pickings: https://code.djangoproject.com/query?status=!closed&easy=1
|
|
|
|
.. _new-contributors-faq:
|
|
|
|
FAQ
|
|
---
|
|
|
|
1. **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 developers), 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.
|
|
|
|
2. **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.
|