Skip to content

Commit 6b98942

Browse files
authored
Explain that the contributors should base changes against main (#983)
This isn't a particularly common issue but every now and then somebody will waste their time by preparing a change against a maintenance branch instead of working with `main` from the get-go. This change serves as a reminder to contributors to think about the `main` branch first.
1 parent 10cb312 commit 6b98942

File tree

1 file changed

+53
-36
lines changed

1 file changed

+53
-36
lines changed

getting-started/pull-request-lifecycle.rst

Lines changed: 53 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -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
180187
When creating a pull request for submission, there are several things that you
181188
should 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

Comments
 (0)