Debian Codegraph @

docs/internals/contributing/new-contributors.txt

raw
1 ===========================
2 Advice for new contributors
3 ===========================
4
5 New contributor and not sure what to do? Want to help but just don't know how
6 to get started? This is the section for you.
7
8 .. admonition:: Get up and running!
9
10 If you are new to contributing to Django, the :doc:`/intro/contributing`
11 tutorial will give you an introduction to the tools and the workflow.
12
13 This page contains more general advice on ways you can contribute to Django,
14 and how to approach that.
15
16 If you are looking for a reference on the details of making code contributions,
17 see the :doc:`/internals/contributing/writing-code/index` documentation.
18
19 First steps
20 ===========
21
22 Start with these steps to discover Django's development process.
23
24 Triage tickets
25 --------------
26
27 If an `unreviewed ticket`_ reports a bug, try and reproduce it. If you can
28 reproduce it and it seems valid, make a note that you confirmed the bug and
29 accept the ticket. Make sure the ticket is filed under the correct component
30 area. Consider writing a patch that adds a test for the bug's behavior, even if
31 you don't fix the bug itself. See more at :ref:`how-can-i-help-with-triaging`
32
33 Review patches of accepted tickets
34 ----------------------------------
35
36 This will help you build familiarity with the codebase and processes. Mark the
37 appropriate flags if a patch needs docs or tests. Look through the changes a
38 patch makes, and keep an eye out for syntax that is incompatible with older but
39 still supported versions of Python. :doc:`Run the tests
40 </internals/contributing/writing-code/unit-tests>` and make sure they pass.
41 Where possible and relevant, try them out on a database other than SQLite.
42 Leave comments and feedback!
43
44 Keep old patches up-to-date
45 ---------------------------
46
47 Oftentimes the codebase will change between a patch being submitted and the
48 time it gets reviewed. Make sure it still applies cleanly and functions as
49 expected. Updating a patch is both useful and important! See more on
50 :doc:`writing-code/submitting-patches`.
51
52 Write some documentation
53 ------------------------
54
55 Django's documentation is great but it can always be improved. Did you find a
56 typo? Do you think that something should be clarified? Go ahead and suggest a
57 documentation patch! See also the guide on :doc:`writing-documentation`.
58
59 .. note::
60
61 The `reports page`_ contains links to many useful Trac queries, including
62 several that are useful for triaging tickets and reviewing patches as
63 suggested above.
64
65 .. _reports page: https://code.djangoproject.com/wiki/Reports
66
67 Sign the Contributor License Agreement
68 --------------------------------------
69
70 The code that you write belongs to you or your employer. If your contribution
71 is more than one or two lines of code, you need to sign the `CLA`_. See the
72 `Contributor License Agreement FAQ`_ for a more thorough explanation.
73
74 .. _CLA: https://www.djangoproject.com/foundation/cla/
75 .. _Contributor License Agreement FAQ: https://www.djangoproject.com/foundation/cla/faq/
76 .. _unreviewed ticket: https://code.djangoproject.com/query?status=!closed&stage=Unreviewed
77
78
79 Guidelines
80 ==========
81
82 As a newcomer on a large project, it's easy to experience frustration. Here's
83 some advice to make your work on Django more useful and rewarding.
84
85 Pick a subject area
86 -------------------
87
88 This should be something that you care about, that you are familiar with or
89 that you want to learn about. You don't already have to be an expert on the
90 area you want to work on; you become an expert through your ongoing
91 contributions to the code.
92
93 Analyze tickets' context and history
94 ------------------------------------
95
96 Trac isn't an absolute; the context is just as important as the words. When
97 reading Trac, you need to take into account who says things, and when they were
98 said. Support for an idea two years ago doesn't necessarily mean that the idea
99 will still have support. You also need to pay attention to who *hasn't* spoken
100 -- for example, if an experienced contributor hasn't been recently involved in
101 a discussion, then a ticket may not have the support required to get into
102 Django.
103
104 Start small
105 -----------
106
107 It's easier to get feedback on a little issue than on a big one. See the
108 `easy pickings`_.
109
110 Confirm support before engaging in a big task
111 ---------------------------------------------
112
113 This means getting someone else to confirm that a bug is real before you fix
114 the issue, and ensuring that there's consensus on a proposed feature before you
115 go implementing it.
116
117 Be bold! Leave feedback!
118 ------------------------
119
120 Sometimes it can be scary to put your opinion out to the world and say "this
121 ticket is correct" or "this patch needs work", but it's the only way the
122 project moves forward. The contributions of the broad Django community
123 ultimately have a much greater impact than that of any one person. We can't do
124 it without **you**!
125
126 Be cautious when marking things "Ready For Check-in"
127 ----------------------------------------------------
128
129 If you're really not certain if a ticket is ready, don't mark it as such. Leave
130 a comment instead, letting others know your thoughts. If you're mostly certain,
131 but not completely certain, you might also try asking on the
132 ``#contributing-getting-started`` channel in the `Django Discord server`_ to
133 see if someone else can confirm your suspicions.
134
135 .. _`Django Discord server`: https://chat.djangoproject.com
136
137 Wait for feedback, and respond to feedback that you receive
138 -----------------------------------------------------------
139
140 Focus on one or two tickets, see them through from start to finish, and repeat.
141 The shotgun approach of taking on lots of tickets and letting some fall by the
142 wayside ends up doing more harm than good.
143
144 Be rigorous
145 -----------
146
147 When we say ":pep:`8`, and must have docs and tests", we mean it. If a patch
148 doesn't have docs and tests, there had better be a good reason. Arguments like
149 "I couldn't find any existing tests of this feature" don't carry much weight.
150 While it may be true, that means you have the extra-important job of writing
151 the very first tests for that feature, not that you get a pass from writing
152 tests altogether.
153
154 Be patient
155 ----------
156
157 It's not always easy for your ticket or your patch to be reviewed quickly. This
158 isn't personal. There are a lot of tickets and pull requests to get through.
159
160 Keeping your patch up to date is important. Review the ticket on Trac to ensure
161 that the *Needs tests*, *Needs documentation*, and *Patch needs improvement*
162 flags are unchecked once you've addressed all review comments.
163
164 Remember that Django has an eight-month release cycle, so there's plenty of
165 time for your patch to be reviewed.
166
167 Finally, a well-timed reminder can help. See :ref:`contributing code FAQ
168 <new-contributors-faq>` for ideas here.
169
170 .. _easy pickings: https://code.djangoproject.com/query?status=!closed&easy=1