<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?
* Has the test suite been run?

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.


NEWS Entries
------------

Almost all changes made to the code base deserve an entry in ``Misc/NEWS``.
The ``What's New in Python`` document is the place for more subjective
judgments of the "importance" of changes. There are two notable exceptions
to this general principle, and they both relate to changes that *already*
have a NEWS entry, and have not yet been included in any formal release
(including alpha and beta releases). These exceptions are:

* If a change is reverted prior to release, then the corresponding entry
  is simply removed. Otherwise, a new entry must be added noting that the
  change has been reverted (e.g. when a feature is released in an alpha and
  then cut prior to the first beta)

* If a change is a fix (or other adjustment) to an earlier unreleased change
  and the original NEWS entry remains valid, then no additional entry is
  needed.

New NEWS entries are customarily added at or near the top of their
respective sections, so that entries within a section appear in approximate
order from newest to oldest.  However, this is customary and not a
requirement.

A nice trick to make Mercurial’s automatic file merge work more smoothly
is to put a new entry after the first or first two entries rather than
at the very top.  This way if you commit, pull new changesets and merge,
the merge will succeed automatically.


Commit Messages
---------------

Every commit has a commit message to document why a change was made and to
communicate that reason to other core developers. Python core developers have
developed a standard way of formatting commit messages that everyone is
expected to follow.

Our usual convention mimics that used in the ``Misc/NEWS`` file.  Actually,
it is common to simply paste the NEWS entry into the commit message.  Here
is an example::

   Issue #42: the spam module is now more spammy.
   The spam module sporadically came up short on spam. This change
   raises the amount of spam in the module by making it more spammy.
   Thanks to Monty Python for the patch.
<commit_msg>Add info about new NEWS handling.<commit_after>.. _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?
* Has the test suite been run?

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.


NEWS Entries
------------

Almost all changes made to the code base deserve an entry in ``Misc/NEWS``.
The ``What's New in Python`` document is the place for more subjective
judgments of the "importance" of changes. There are two notable exceptions
to this general principle, and they both relate to changes that *already*
have a NEWS entry, and have not yet been included in any formal release
(including alpha and beta releases). These exceptions are:

* If a change is reverted prior to release, then the corresponding entry
  is simply removed. Otherwise, a new entry must be added noting that the
  change has been reverted (e.g. when a feature is released in an alpha and
  then cut prior to the first beta).

* If a change is a fix (or other adjustment) to an earlier unreleased change
  and the original NEWS entry remains valid, then no additional entry is
  needed.

New NEWS entries are customarily added at or near the top of their
respective sections, so that entries within a section appear in approximate
order from newest to oldest.  However, this is customary and not a
requirement.

The NEWS file is now read by Sphinx to produce the "Changelog" page; accordingly
it should be valid reStructuredText.  The "default role" (single backticks) can
be used to refer to objects in the documentation.  Example NEWS entry::

   - Issue #15304: Fix warning message when `os.chdir()` fails inside
     `test.support.temp_cwd()`.  Patch by <NAME>.

(In all other ``.rst`` files, the single backticks should not be used.  They are
allowed here because NEWS is meant to be as readable as possible unprocessed.)

A nice trick to make Mercurial’s automatic file merge work more smoothly is to
put a new entry after the first or first two entries rather than at the very
top.  This way if you commit, pull new changesets and merge, the merge will
succeed automatically.


Commit Messages
---------------

Every commit has a commit message to document why a change was made and to
communicate that reason to other core developers. Python core developers have
developed a standard way of formatting commit messages that everyone is
expected to follow.

Our usual convention mimics that used in the ``Misc/NEWS`` file.  Actually,
it is common to simply paste the NEWS entry into the commit message.  Here
is an example::

   Issue #42: the spam module is now more spammy.
   The spam module sporadically came up short on spam. This change
   raises the amount of spam in the module by making it more spammy.
   Thanks to Monty Python for the patch.

{'fraction_non_alphanumeric': 0.06619771385504333, 'fraction_numerical': 0.0011305112423062428, 'mean_word_length': 3.9392059553349874, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 4, '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': '54757', 'n_tokens_mistral': 2065, 'n_tokens_neox': 1972, 'n_words': 1252}