<commit_before>.. _committing:

Committing and Pushing Changes
==============================

Once a change patch is ready and tested, it can be committed to the repository.
We usually prefer to put a whole feature or bugfix into a single commit, but no
more.  In particular:

* Do **not** fix more than one issue in the same commit (except, of course, if
  one code change fixes all of them).
* Do **not** do cosmetic changes to unrelated code in the same commit as some
  feature/bugfix.

It is of course okay to pile up several commits to one branch and merge them
into another in one merge commit.


Patch Checklist
---------------

Here's the simple patch checklist that ``make patchcheck`` (or ``./python.exe
Tools/scripts/patchcheck.py`` on Windows) will run through
on a system that uses the makefile to build Python:

* Are there any whitespace problems in Python files?
  (using ``Tools/scripts/reindent.py``)
* Are there any whitespace problems in C files?
* Are there any whitespace problems in the documentation?
  (using ``Tools/scripts/reindent-rst.py``)
* Has the documentation been updated?
* Has the test suite been updated?
* Has ``Misc/NEWS`` been updated?
* Has ``Misc/ACKS`` been updated?
* Has ``configure`` been regenerated, if necessary?
* Has ``pyconfig.h.in`` been regenerated, if necessary?

Note that the automated patch check can't actually *answer* all of these
questions, and even if it could, it still wouldn't know whether or not
those answers were appropriate. Aside from the whitespace checks, it is just
a memory aid to help with remembering the various elements that can go into
making a complete patch.


Handling Others' Code
---------------------

As a core developer you will occasionally want to commit a patch created by
someone else. When doing so you will want to make sure of some things.

First, make sure the patch is in a good state. Both :ref:`patch` and
:ref:`helptriage`
explain what is to be expected of a patch. Typically patches that get cleared by
triagers are good to go except maybe lacking ``Misc/ACKS`` and ``Misc/NEWS``
entries.

Second, make sure the patch does not break backwards-compatibility without a
good reason. This means :ref:`running the test suite <runtests>` to make sure
everything still passes. It also means that if semantics do change there must
be a good reason for the breakage of code the change will cause (and it
**will** break someone's code). If you are unsure if the breakage is worth it,
ask on python-dev.

Third, ensure the patch is attributed correctly by adding the contributor's
name to ``Misc/ACKS`` if they aren't already there (and didn't add themselves
in their patch) and by mentioning "Patch by <x>" in the ``Misc/NEWS`` entry<commit_msg>Issue #18871: make it more explicit that the test suite should be run before committing<commit_after>.. _committing:

Committing and Pushing Changes
==============================

Is the change ready for committing?
-----------------------------------

Before a change is committed, you must make sure it is ready to enter the
public source tree.  Draft commits are prohibited.  Therefore, you must
ensure your changes fulfill several mandatory criteria.

.. note::
   If you want to share your work-in-progress code on a feature or bugfix,
   either publish patches or create a public fork of the repository.


Does the test suite still pass?
'''''''''''''''''''''''''''''''

You must :ref:`run the whole test suite <runtests>` to ensure that it
passes before pushing any code changes.

.. note::
   You really need to run the **entire** test suite.  Running a single test
   is not enough as your changes may have unforeseen effects on other tests
   or library modules.

   Running the entire test suite doesn't guarantee that your changes
   will pass the :ref:`continuous integration <buildbots>` tests, as those
   will exercise more possibilities still (such as different platforms or
   build options).  But it will at least catch non-build specific,
   non-platform specific errors, therefore minimizing the chance for
   breakage.

Patch checklist
'''''''''''''''

Apart from running the tests, there's a simple patch checklist that
``make patchcheck`` (or ``./python.exe Tools/scripts/patchcheck.py`` on
Windows) will run through:

* Are there any whitespace problems in Python files?
  (using ``Tools/scripts/reindent.py``)
* Are there any whitespace problems in C files?
* Are there any whitespace problems in the documentation?
  (using ``Tools/scripts/reindent-rst.py``)
* Has the documentation been updated?
* Has the test suite been updated?
* Has ``Misc/NEWS`` been updated?
* Has ``Misc/ACKS`` been updated?
* Has ``configure`` been regenerated, if necessary?
* Has ``pyconfig.h.in`` been regenerated, if necessary?

Note that the automated patch check can't actually *answer* all of these
questions, and even if it could, it still wouldn't know whether or not
those answers were appropriate. Aside from the whitespace checks, it is just
a memory aid to help with remembering the various elements that can go into
making a complete patch.


Commit Style
------------

Once a change patch is ready and tested, it can be committed to the repository.
We usually prefer to put a whole feature or bugfix into a single commit, but no
more.  In particular:

* Do **not** fix more than one issue in the same commit (except, of course, if
  one code change fixes all of them).
* Do **not** do cosmetic changes to unrelated code in the same commit as some
  feature/bugfix.

It is of course okay to pile up several commits to one branch and merge them
into another in one merge commit.


Handling Others' Code
---------------------

As a core developer you will occasionally want to commit a patch created by
someone else. When doing so you will want to make sure of some things.

First, make sure the patch is in a good state. Both :ref:`patch` and
:ref:`helptriage`
explain what is to be expected of a patch. Typically patches that get cleared by
triagers are good to go except maybe lacking ``Misc/ACKS`` and ``Misc/NEWS``
entries.

Second, make sure the patch does not break backwards-compatibility without a
good reason. This means :ref:`running the entire test suite <runtests>` to
make sure everything still passes. It also means that if semantics do change
there must be a good reason for the breakage of code the change will cause
(and it **will** break someone's code). If you are unsure if the breakage
is worth it, ask on python-dev.

Third, ensure the patch is attributed correctly by adding the contributor's
name to ``Misc/ACKS`` if they aren't already there (and didn't add themselves
in their patch) and by mentioning "Patch by <x>" in the ``Misc/NEWS`` entry
{'fraction_non_alphanumeric': 0.09265318262938727, 'fraction_numerical': 0.00074360499702558, 'mean_word_length': 4.011177347242921, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6222628', 'n_tokens_mistral': 1776, 'n_tokens_neox': 1703, 'n_words': 1010}