Skip to content

Explain that the contributors should base changes against main #983

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 11, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 53 additions & 36 deletions getting-started/pull-request-lifecycle.rst
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,8 @@ Here is a quick overview of how you can contribute to CPython:

#. `Create an issue`_ that describes your change [*]_

#. :ref:`Create a new branch in Git <pullrequest-steps>`
#. :ref:`Create a new branch in Git <pullrequest-steps>` from the
``main`` branch

#. Work on changes (e.g. fix a bug or add a new feature)

Expand Down Expand Up @@ -79,10 +80,16 @@ You should have already :ref:`set up your system <setup>`,

git fetch upstream

* Create a new branch in your local clone::
* Create a new branch in your local clone from the ``main`` branch
in the upstream repository::

git checkout -b <branch-name> upstream/main

.. note::
Almost all changes to Python, including bug fixes, should first be
made against the ``main`` branch. See :ref:`here <good-prs>` for
more details.

* Make changes to the code, and use ``git status`` and ``git diff`` to see them.

(Learn more about :ref:`good-prs`)
Expand Down Expand Up @@ -180,40 +187,50 @@ Making Good PRs
When creating a pull request for submission, there are several things that you
should do to help ensure that your pull request is accepted.

First, make sure to follow Python's style guidelines. For Python code you
should follow :PEP:`8`, and for C code you should follow :PEP:`7`. If you have
one or two discrepancies those can be fixed by the core developer who merges
your pull request. But if you have systematic deviations from the style guides
your pull request will be put on hold until you fix the formatting issues.

.. note::
Pull requests with only code formatting changes are usually rejected. On the other
hand, fixes for typos and grammar errors in documents and docstrings are
welcome.

Second, be aware of backwards-compatibility considerations. While the core
developer who eventually handles your pull request will make the final call on
whether something is acceptable, thinking about backwards-compatibility early
will help prevent having your pull request rejected on these grounds. Put
yourself in the shoes of someone whose code will be broken by the change(s)
introduced by the pull request. It is quite likely that any change made will
break someone's code, so you need to have a good reason to make a change as
you will be forcing someone to update their code. (This obviously does not
apply to new classes or functions; new arguments should be optional and have
default values which maintain the existing behavior.) If in doubt, have a look
at :PEP:`387` or :ref:`discuss <communication>` the issue with experienced
developers.

Third, make sure you have proper tests to verify your pull request works as
expected. Pull requests will not be accepted without the proper tests!

Fourth, make sure the entire test suite :ref:`runs <runtests>` **without
failure** because of your changes. It is not sufficient to only run whichever
test seems impacted by your changes, because there might be interferences
unknown to you between your changes and some other part of the interpreter.

Fifth, proper :ref:`documentation <documenting>`
additions/changes should be included.
#. **Make your change against the right version of Python.** In general all
changes are made against the ``main`` branch first. This includes bug fixes.
After the change is merged there, it will be :ref:`ported back <branch-merge>`
to older :ref:`maintenance releases <branchstatus>` as well. That way we
ensure all affected versions are handled. Therefore, basing a new change
directly on a maintenance branch is only used in specific circumstances,
for instance when that change does not apply to ``main`` or the change
requires a different approach in an older Python version compared to
``main``.

#. **Make sure to follow Python's style guidelines.** For Python code you
should follow :PEP:`8`, and for C code you should follow :PEP:`7`. If you have
one or two discrepancies those can be fixed by the core developer who merges
your pull request. But if you have systematic deviations from the style guides
your pull request will be put on hold until you fix the formatting issues.

.. note::
Pull requests with only code formatting changes are usually rejected. On
the other hand, fixes for typos and grammar errors in documents and
docstrings are welcome.

#. **Be aware of backwards-compatibility considerations.** While the core
developer who eventually handles your pull request will make the final call on
whether something is acceptable, thinking about backwards-compatibility early
will help prevent having your pull request rejected on these grounds. Put
yourself in the shoes of someone whose code will be broken by the change(s)
introduced by the pull request. It is quite likely that any change made will
break someone's code, so you need to have a good reason to make a change as
you will be forcing someone to update their code. (This obviously does not
apply to new classes or functions; new arguments should be optional and have
default values which maintain the existing behavior.) If in doubt, have a look
at :PEP:`387` or :ref:`discuss <communication>` the issue with experienced
developers.

#. **Make sure you have proper tests** to verify your pull request works as
expected. Pull requests will not be accepted without the proper tests!

#. **Make sure all tests pass.** The entire test suite needs to
:ref:`run <runtests>` **without failure** because of your changes.
It is not sufficient to only run whichever test seems impacted by your
changes, because there might be interferences unknown to you between your
changes and some other part of the interpreter.

#. Proper :ref:`documentation <documenting>` additions/changes should be included.


.. _patchcheck:
Expand Down