diff --git a/core-developers/committing.rst b/core-developers/committing.rst index 326578c0b..4d0282d41 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -72,104 +72,10 @@ to enter the public source tree. Ask yourself the following questions: significant improvements, or backwards-incompatible changes), then an entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added as well. Changes that affect only documentation generally do not - require a ``NEWS`` entry. (See the following section for more information.) - -.. _news-entry: -.. _what-s-new-and-news-entries: - -Updating NEWS and What's New in Python --------------------------------------- - -Changes that require NEWS entries -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Most changes made to the codebase deserve an entry in :cpy-file:`Misc/NEWS.d`, -except for the following: - -* documentation changes -* test changes -* strictly internal changes with no user-visible effects -* changes that already have a ``NEWS`` entry -* reverts that have not yet been included in any formal release - (including alpha and beta releases) - -For the last two, note the following: - -#. **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 (for example, 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. - -Changes that require "What's New in Python" entries -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If a change is particularly interesting for end users (for example, new features, -significant improvements, or backwards-incompatible changes), add an entry in -the "What's New in Python" document (in :cpy-file:`Doc/whatsnew/`) -in addition to the ``NEWS`` entry. - -In most cases, it is sufficient to reuse the wording from the ``NEWS`` entry -in the "What's New in Python" entry. - -.. note:: - - A change that needs an entry in "What's New in Python", - is very likely not suitable for inclusion in a maintenance release. - -How to add a NEWS entry -^^^^^^^^^^^^^^^^^^^^^^^ - -``NEWS`` entries go into the ``Misc/NEWS.d`` directory as individual files. The -``NEWS`` entry can be created by using `blurb-it `_, -or the :pypi:`blurb` tool and its ``blurb add`` command. - -If you are unable to use the tool, then you can create the ``NEWS`` entry file -manually. The ``Misc/NEWS.d`` directory contains a sub-directory named -``next``, which contains various sub-directories representing classifications -for what was affected (for example, ``Misc/NEWS.d/next/Library`` for changes relating -to the standard library). The file name itself should be in the format -``.gh-issue-..rst``: - -* ```` is today's date joined with a hyphen (``-``) to your current - local time, in the ``YYYY-MM-DD-hh-mm-ss`` format (for example, ``2017-05-27-16-46-23``). -* ```` is the issue number the change is for (for example, ``12345`` - for ``gh-issue-12345``). -* ```` is a unique string to guarantee that the file name is - unique across branches (for example, ``Yl4gI2``). It is typically six characters - long, but it can be any length of letters and numbers. Its uniqueness - can be satisfied by typing random characters on your keyboard. - -As a result, a file name can look something like -``Misc/NEWS.d/next/Library/2017-05-27-16-46-23.gh-issue-12345.Yl4gI2.rst``. - -How to write a NEWS entry -^^^^^^^^^^^^^^^^^^^^^^^^^ - -All ``NEWS`` entries end up being part of the changelog. -The changelog contains *a lot* of entries, -and its intended audience is mainly users, not core devs and contributors. -Take this into consideration when wording your ``NEWS`` entry. -Describe the user-visible effects of your change succinctly and accurately; -avoid long technical elaborations, digressions, and do not expect or require -the reader to have read the actual diff for the change. - -The contents of a ``NEWS`` file should be valid reStructuredText. An 80 character -column width should be used. There is no indentation or leading marker in the -file (for example, ``-``). There is also no need to start the entry with the issue -number since it is part of the file name. You can use -:ref:`inline markups ` too. Here is an example of a ``NEWS`` -entry:: - - Fix warning message when :func:`os.chdir` fails inside - :func:`test.support.temp_cwd`. Contributed by Chris Jerdonek. - -The inline Sphinx roles like ``:func:`` can be used help readers -find more information. You can build HTML and verify that the -link target is appropriate by using :ref:`make html `. + require a ``NEWS`` entry. + + .. seealso:: + :ref:`what-s-new-and-news-entries` Working with Git_ diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index 59242f13f..a817b1313 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -237,6 +237,105 @@ should do to help ensure that your pull request is accepted. #. Proper :ref:`documentation ` additions/changes should be included. +.. _news-entry: +.. _what-s-new-and-news-entries: + +Updating NEWS and What's New in Python +====================================== + +Changes that require NEWS entries +--------------------------------- + +Most changes made to the codebase deserve an entry in :cpy-file:`Misc/NEWS.d`, +except for the following: + +* documentation changes +* test changes +* strictly internal changes with no user-visible effects +* changes that already have a ``NEWS`` entry +* reverts that have not yet been included in any formal release + (including alpha and beta releases) + +For the last two, note the following: + +#. **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 (for example, 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. + +Changes that require "What's New in Python" entries +--------------------------------------------------- + +If a change is particularly interesting for end users (for example, new features, +significant improvements, or backwards-incompatible changes), add an entry in +the "What's New in Python" document (in :cpy-file:`Doc/whatsnew/`, the 3.X.rst +file where X is the current Python version) in addition to the ``NEWS`` entry. + +In most cases, it is sufficient to reuse the wording from the ``NEWS`` entry +in the "What's New in Python" entry. + +.. note:: + + A change that needs an entry in "What's New in Python" + is very likely not suitable for inclusion in a maintenance release. + +How to add a NEWS entry +----------------------- + +``NEWS`` entries go into the ``Misc/NEWS.d`` directory as individual files. The +``NEWS`` entry can be created by using `blurb-it `_, +or the :pypi:`blurb` tool and its ``blurb add`` command. + +If you are unable to use the tool, then you can create the ``NEWS`` entry file +manually. The ``Misc/NEWS.d`` directory contains a sub-directory named +``next``, which contains various sub-directories representing classifications +for what was affected (for example, ``Misc/NEWS.d/next/Library`` for changes relating +to the standard library). The file name itself should be in the format +``.gh-issue-..rst``: + +* ```` is today's date joined with a hyphen (``-``) to your current + local time, in the ``YYYY-MM-DD-hh-mm-ss`` format (for example, ``2017-05-27-16-46-23``). +* ```` is the issue number the change is for (for example, ``12345`` + for ``gh-issue-12345``). +* ```` is a unique string to guarantee that the file name is + unique across branches (for example, ``Yl4gI2``). It is typically six characters + long, but it can be any length of letters and numbers. Its uniqueness + can be satisfied by typing random characters on your keyboard. + +As a result, a file name can look something like +``Misc/NEWS.d/next/Library/2017-05-27-16-46-23.gh-issue-12345.Yl4gI2.rst``. + +How to write a NEWS entry +------------------------- + +All ``NEWS`` entries end up being part of the changelog. +The changelog contains *a lot* of entries, +and its intended audience is mainly users, not core devs and contributors. +Take this into consideration when wording your ``NEWS`` entry. +Describe the user-visible effects of your change succinctly and accurately; +avoid long technical elaborations, digressions, and do not expect or require +the reader to have read the actual diff for the change. + +The contents of a ``NEWS`` file should be valid reStructuredText. An 80 character +column width should be used. There is no indentation or leading marker in the +file (for example, ``-``). There is also no need to start the entry with the issue +number since it is part of the file name. You can use +:ref:`inline markups ` too. Here is an example of a ``NEWS`` +entry: + +.. code-block:: rst + + Fix warning message when :func:`os.chdir` fails inside + :func:`test.support.temp_cwd`. Contributed by Chris Jerdonek. + +The inline Sphinx roles like :rst:role:`:func: ` can be used help readers +find more information. You can build HTML and verify that the +link target is appropriate by using :ref:`make html `. + Copyrights ========== pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy