mirror of
https://github.com/django/django.git
synced 2024-11-25 16:09:27 +01:00
4a954cfd11
This patch does not remove all occurrences of the words in question. Rather, I went through all of the occurrences of the words listed below, and judged if they a) suggested the reader had some kind of knowledge/experience, and b) if they added anything of value (including tone of voice, etc). I left most of the words alone. I looked at the following words: - simply/simple - easy/easier/easiest - obvious - just - merely - straightforward - ridiculous Thanks to Carlton Gibson for guidance on how to approach this issue, and to Tim Bell for providing the idea. But the enormous lion's share of thanks go to Adam Johnson for his patient and helpful review.
157 lines
6.2 KiB
Plaintext
157 lines
6.2 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.
|
|
|
|
.. admonition:: Basic tools and workflow
|
|
|
|
If you are new to contributing to Django, the :doc:`/intro/contributing`
|
|
tutorial will give you an introduction to the tools and the workflow.
|
|
|
|
First steps
|
|
===========
|
|
|
|
Start with these steps 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. :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**
|
|
|
|
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**
|
|
|
|
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::
|
|
|
|
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 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**
|
|
|
|
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 there's consensus on 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 any one person. 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
|
|
(except the Django fellow), 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.
|