| 1 |
====================== |
| 2 |
FAQ: Contributing code |
| 3 |
====================== |
| 4 |
|
| 5 |
.. _new-contributors-faq: |
| 6 |
|
| 7 |
How can I get started contributing code to Django? |
| 8 |
================================================== |
| 9 |
|
| 10 |
Thanks for asking! We've written an entire document devoted to this question. |
| 11 |
It's titled :doc:`Contributing to Django </internals/contributing/index>`. |
| 12 |
|
| 13 |
I submitted a bug fix several weeks ago. Why are you ignoring my contribution? |
| 14 |
============================================================================== |
| 15 |
|
| 16 |
Don't worry: We're not ignoring you! |
| 17 |
|
| 18 |
It's important to understand there is a difference between "a ticket is being |
| 19 |
ignored" and "a ticket has not been attended to yet." Django's ticket system |
| 20 |
contains hundreds of open tickets, of various degrees of impact on end-user |
| 21 |
functionality, and Django's developers have to review and prioritize. |
| 22 |
|
| 23 |
On top of that: the people who work on Django are all volunteers. As a result, |
| 24 |
the amount of time that we have to work on the framework is limited and will |
| 25 |
vary from week to week depending on our spare time. If we're busy, we may not |
| 26 |
be able to spend as much time on Django as we might want. |
| 27 |
|
| 28 |
The best way to make sure tickets do not get hung up on the way to checkin is |
| 29 |
to make it dead easy, even for someone who may not be intimately familiar with |
| 30 |
that area of the code, to understand the problem and verify the fix: |
| 31 |
|
| 32 |
* Are there clear instructions on how to reproduce the bug? If this |
| 33 |
touches a dependency (such as Pillow), a contrib module, or a specific |
| 34 |
database, are those instructions clear enough even for someone not |
| 35 |
familiar with it? |
| 36 |
|
| 37 |
* If there are several branches linked to the ticket, is it clear what each one |
| 38 |
does, which ones can be ignored and which matter? |
| 39 |
|
| 40 |
* Does the change include a unit test? If not, is there a very clear |
| 41 |
explanation why not? A test expresses succinctly what the problem is, |
| 42 |
and shows that the branch actually fixes it. |
| 43 |
|
| 44 |
If your contribution is not suitable for inclusion in Django, we won't ignore |
| 45 |
it -- we'll close the ticket. So if your ticket is still open, it doesn't mean |
| 46 |
we're ignoring you; it just means we haven't had time to look at it yet. |
| 47 |
|
| 48 |
When and how might I remind the team of a change I care about? |
| 49 |
============================================================== |
| 50 |
|
| 51 |
A polite, well-timed message in the forum/branch is one way to get attention. |
| 52 |
To determine the right time, you need to keep an eye on the schedule. If you |
| 53 |
post your message right before a release deadline, you're not likely to get the |
| 54 |
sort of attention you require. |
| 55 |
|
| 56 |
Gentle reminders in the ``#contributing-getting-started`` channel in the |
| 57 |
`Django Discord server`_ can work. |
| 58 |
|
| 59 |
Another way to get traction is to pull several related tickets together. When |
| 60 |
someone sits down to review a bug in an area they haven't touched for |
| 61 |
a while, it can take a few minutes to remember all the fine details of how |
| 62 |
that area of code works. If you collect several minor bug fixes together into |
| 63 |
a similarly themed group, you make an attractive target, as the cost of coming |
| 64 |
up to speed on an area of code can be spread over multiple tickets. |
| 65 |
|
| 66 |
Please refrain from emailing anyone personally or repeatedly raising the same |
| 67 |
issue over and over again. This sort of behavior will not gain you any |
| 68 |
additional attention -- certainly not the attention that you need in order to |
| 69 |
get your issue addressed. |
| 70 |
|
| 71 |
.. _`Django Discord server`: https://chat.djangoproject.com |
| 72 |
|
| 73 |
But I've reminded you several times and you keep ignoring my contribution! |
| 74 |
========================================================================== |
| 75 |
|
| 76 |
Seriously - we're not ignoring you. If your contribution is not suitable for |
| 77 |
inclusion in Django, we will close the ticket. For all the other tickets, we |
| 78 |
need to prioritize our efforts, which means that some tickets will be |
| 79 |
addressed before others. |
| 80 |
|
| 81 |
One of the criteria that is used to prioritize bug fixes is the number of |
| 82 |
people that will likely be affected by a given bug. Bugs that have the |
| 83 |
potential to affect many people will generally get priority over those that |
| 84 |
are edge cases. |
| 85 |
|
| 86 |
Another reason that a bug might be ignored for a while is if the bug is a |
| 87 |
symptom of a larger problem. While we can spend time writing, testing and |
| 88 |
applying lots of little changes, sometimes the right solution is to rebuild. If |
| 89 |
a rebuild or refactor of a particular component has been proposed or is |
| 90 |
underway, you may find that bugs affecting that component will not get as much |
| 91 |
attention. Again, this is a matter of prioritizing scarce resources. By |
| 92 |
concentrating on the rebuild, we can close all the little bugs at once, and |
| 93 |
hopefully prevent other little bugs from appearing in the future. |
| 94 |
|
| 95 |
Whatever the reason, please keep in mind that while you may hit a particular |
| 96 |
bug regularly, it doesn't necessarily follow that every single Django user |
| 97 |
will hit the same bug. Different users use Django in different ways, stressing |
| 98 |
different parts of the code under different conditions. When we evaluate the |
| 99 |
relative priorities, we are generally trying to consider the needs of the |
| 100 |
entire community, instead of prioritizing the impact on one particular user. |
| 101 |
This doesn't mean that we think your problem is unimportant -- just that in the |
| 102 |
limited time we have available, we will always err on the side of making 10 |
| 103 |
people happy rather than making a single person happy. |
| 104 |
|
| 105 |
I'm sure my ticket is absolutely 100% perfect, can I mark it as "Ready For Checkin" myself? |
| 106 |
=========================================================================================== |
| 107 |
|
| 108 |
Sorry, no. It's always better to get another set of eyes on a ticket. If |
| 109 |
you're having trouble getting that second set of eyes, see questions above. |