@@ -29,7 +29,8 @@ Here is a quick overview of how you can contribute to CPython:
29
29
30
30
#. `Create an issue `_ that describes your change [*]_
31
31
32
- #. :ref: `Create a new branch in Git <pullrequest-steps >`
32
+ #. :ref: `Create a new branch in Git <pullrequest-steps >` from the
33
+ ``main `` branch
33
34
34
35
#. Work on changes (e.g. fix a bug or add a new feature)
35
36
@@ -79,10 +80,16 @@ You should have already :ref:`set up your system <setup>`,
79
80
80
81
git fetch upstream
81
82
82
- * Create a new branch in your local clone::
83
+ * Create a new branch in your local clone from the ``main `` branch
84
+ in the upstream repository::
83
85
84
86
git checkout -b <branch-name> upstream/main
85
87
88
+ .. note ::
89
+ Almost all changes to Python, including bug fixes, should first be
90
+ made against the ``main `` branch. See :ref: `here <good-prs >` for
91
+ more details.
92
+
86
93
* Make changes to the code, and use ``git status `` and ``git diff `` to see them.
87
94
88
95
(Learn more about :ref: `good-prs `)
@@ -180,40 +187,50 @@ Making Good PRs
180
187
When creating a pull request for submission, there are several things that you
181
188
should do to help ensure that your pull request is accepted.
182
189
183
- First, make sure to follow Python's style guidelines. For Python code you
184
- should follow :PEP: `8 `, and for C code you should follow :PEP: `7 `. If you have
185
- one or two discrepancies those can be fixed by the core developer who merges
186
- your pull request. But if you have systematic deviations from the style guides
187
- your pull request will be put on hold until you fix the formatting issues.
188
-
189
- .. note ::
190
- Pull requests with only code formatting changes are usually rejected. On the other
191
- hand, fixes for typos and grammar errors in documents and docstrings are
192
- welcome.
193
-
194
- Second, be aware of backwards-compatibility considerations. While the core
195
- developer who eventually handles your pull request will make the final call on
196
- whether something is acceptable, thinking about backwards-compatibility early
197
- will help prevent having your pull request rejected on these grounds. Put
198
- yourself in the shoes of someone whose code will be broken by the change(s)
199
- introduced by the pull request. It is quite likely that any change made will
200
- break someone's code, so you need to have a good reason to make a change as
201
- you will be forcing someone to update their code. (This obviously does not
202
- apply to new classes or functions; new arguments should be optional and have
203
- default values which maintain the existing behavior.) If in doubt, have a look
204
- at :PEP: `387 ` or :ref: `discuss <communication >` the issue with experienced
205
- developers.
206
-
207
- Third, make sure you have proper tests to verify your pull request works as
208
- expected. Pull requests will not be accepted without the proper tests!
209
-
210
- Fourth, make sure the entire test suite :ref: `runs <runtests >` **without
211
- failure ** because of your changes. It is not sufficient to only run whichever
212
- test seems impacted by your changes, because there might be interferences
213
- unknown to you between your changes and some other part of the interpreter.
214
-
215
- Fifth, proper :ref: `documentation <documenting >`
216
- additions/changes should be included.
190
+ #. **Make your change against the right version of Python. ** In general all
191
+ changes are made against the ``main `` branch first. This includes bug fixes.
192
+ After the change is merged there, it will be :ref: `ported back <branch-merge >`
193
+ to older :ref: `maintenance releases <branchstatus >` as well. That way we
194
+ ensure all affected versions are handled. Therefore, basing a new change
195
+ directly on a maintenance branch is only used in specific circumstances,
196
+ for instance when that change does not apply to ``main `` or the change
197
+ requires a different approach in an older Python version compared to
198
+ ``main ``.
199
+
200
+ #. **Make sure to follow Python's style guidelines. ** For Python code you
201
+ should follow :PEP: `8 `, and for C code you should follow :PEP: `7 `. If you have
202
+ one or two discrepancies those can be fixed by the core developer who merges
203
+ your pull request. But if you have systematic deviations from the style guides
204
+ your pull request will be put on hold until you fix the formatting issues.
205
+
206
+ .. note ::
207
+ Pull requests with only code formatting changes are usually rejected. On
208
+ the other hand, fixes for typos and grammar errors in documents and
209
+ docstrings are welcome.
210
+
211
+ #. **Be aware of backwards-compatibility considerations. ** While the core
212
+ developer who eventually handles your pull request will make the final call on
213
+ whether something is acceptable, thinking about backwards-compatibility early
214
+ will help prevent having your pull request rejected on these grounds. Put
215
+ yourself in the shoes of someone whose code will be broken by the change(s)
216
+ introduced by the pull request. It is quite likely that any change made will
217
+ break someone's code, so you need to have a good reason to make a change as
218
+ you will be forcing someone to update their code. (This obviously does not
219
+ apply to new classes or functions; new arguments should be optional and have
220
+ default values which maintain the existing behavior.) If in doubt, have a look
221
+ at :PEP: `387 ` or :ref: `discuss <communication >` the issue with experienced
222
+ developers.
223
+
224
+ #. **Make sure you have proper tests ** to verify your pull request works as
225
+ expected. Pull requests will not be accepted without the proper tests!
226
+
227
+ #. **Make sure all tests pass. ** The entire test suite needs to
228
+ :ref: `run <runtests >` **without failure ** because of your changes.
229
+ It is not sufficient to only run whichever test seems impacted by your
230
+ changes, because there might be interferences unknown to you between your
231
+ changes and some other part of the interpreter.
232
+
233
+ #. Proper :ref: `documentation <documenting >` additions/changes should be included.
217
234
218
235
219
236
.. _patchcheck :
0 commit comments