@@ -29,7 +29,8 @@ Here is a quick overview of how you can contribute to CPython:
2929
3030#. `Create an issue `_ that describes your change [*]_
3131
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
3334
3435#. Work on changes (e.g. fix a bug or add a new feature)
3536
@@ -79,10 +80,16 @@ You should have already :ref:`set up your system <setup>`,
7980
8081 git fetch upstream
8182
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::
8385
8486 git checkout -b <branch-name> upstream/main
8587
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+
8693* Make changes to the code, and use ``git status `` and ``git diff `` to see them.
8794
8895 (Learn more about :ref: `good-prs `)
@@ -180,40 +187,50 @@ Making Good PRs
180187When creating a pull request for submission, there are several things that you
181188should do to help ensure that your pull request is accepted.
182189
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.
217234
218235
219236.. _patchcheck :
0 commit comments