8000 Document the news file format by brettcannon · Pull Request #212 · python/devguide · GitHub
[go: up one dir, main page]

Skip to content

Document the news file format #212

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 10 commits into from
Jun 23, 2017
80 changes: 48 additions & 32 deletions committing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ later in this document):
#. Was ``configure`` regenerated (if necessary)?
#. Was ``pyconfig.h.in`` regenerated (if necessary)?
#. Was the submitter added to ``Misc/ACKS`` (as appropriate)?
#. Was ``Misc/NEWS`` updated (as appropriate)?
#. Was an entry added under ``Misc/NEWS.d/next`` (as appropriate)?
#. Was "What's New" updated (as appropriate)?
#. Were appropriate labels added to signify necessary backporting of the
pull request?
Expand All @@ -32,7 +32,7 @@ later in this document):
If you want to share your work-in-progress code on a feature or bugfix,
either open a ``WIP``-prefixed PR, publish patches on the
`issue tracker`_ or create a public fork of the repository.

.. _issue tracker: https://bugs.python.org


Expand Down Expand Up @@ -79,7 +79,7 @@ The automated patch checklist runs through:
(using ``Tools/scripts/reindent-rst.py``)
* Has the documentation been updated?
* Has the test suite been updated?
* Has ``Misc/NEWS`` been updated?
* Has an entry under ``Misc/NEWS.d/next`` been added?
* Has ``Misc/ACKS`` been updated?
* Has ``configure`` been regenerated, if necessary?
* Has ``pyconfig.h.in`` been regenerated, if necessary?
Expand Down Expand Up @@ -115,7 +115,7 @@ 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``
triagers are good to go except maybe lacking ``Misc/ACKS`` and ``Misc/NEWS.d``
entries (which a core developer should make sure are updated appropriately).

Second, make sure the patch does not break backwards-compatibility without a
Expand All @@ -127,12 +127,12 @@ is worth it, ask on python-dev.

Third, ensure the patch is attributed correctly with the contributor's
name in ``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
in their patch) and by mentioning "Patch by <x>" in the ``Misc/NEWS.d`` entry
and the checkin message. If the patch has been heavily modified then "Initial
patch by <x>" is an appropriate alternate wording.

If you omit correct attribution in the initial checkin, then update ``ACKS``
and ``NEWS`` in a subsequent checkin (don't worry about trying to fix the
and ``NEWS.d`` in a subsequent checkin (don't worry about trying to fix the
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Generally accepted usage is "check-in" for a noun or adjective or "check in" for a verb. No need to update for this PR as it's "checkin" throughout the document. Future revisions should probably correct this.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can't point that out to the son of a former school teacher who almost had a minor in English and expect them not to fix it immediately. 😉

original checkin message in that case).

Finally, make sure that the submitter of the
Expand Down Expand Up @@ -171,17 +171,17 @@ for inclusion.
https://www.python.org/psf/contrib/contrib-form/


What's New and NEWS Entries
What's New and News Entries
---------------------------

Almost all changes made to the code base deserve an entry in ``Misc/NEWS``.
Almost all changes made to the code base deserve an entry in ``Misc/NEWS.d``.
If the change is particularly interesting for end users (e.g. new features,
significant improvements, or backwards-incompatible changes), an entry in
the ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added
as well.

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
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:

Expand All @@ -191,7 +191,7 @@ These exceptions are:
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
and the original news entry remains valid, then no additional entry is
needed.

Needing a What's New entry almost always means that a change is *not*
Expand All @@ -201,25 +201,41 @@ when implemented, these changes *must* be noted in the "New Additions in
Python 2.7 Maintenance Releases" section of the Python 2.7 What's New
document.

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.
News entries go into the ``Misc/NEWS.d`` directory as individual files. The
easiest way to create a news entry is to use the
`blurb <https://pypi.org/project/blurb/>`_ tool and its ``blurb add`` command.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will blurb add open some editor or editing window?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe it will open an editor, yes.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It opens $EDITOR.

If $EDITOR isn't set, it will try a sane default on some platforms ("notepad" on Windows, /etc/alternatives/editor on Linux (if present)). I think when Ned got it working on macOS he said it shouldn't try to guess on that platform.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Notepad is definitely lightweight, and for a typical news item, should be fine.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the editor is not set on macOS, it seems reasonable to default to TextEdit which is what the operating system does.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This level of discussion is more appropriate in the core-workflow issue tracker.


If you are unable to use the tool you can create the news entry file manually.
The ``Misc/NEWS.d`` directory contains a sub-directory named ``next`` which
itself contains various sub-directories representing classifications for what
was affected (e.g. ``Misc/NEWS.d/next/Library`` for changes relating to the
standard library). The file name itself should be of the format
``<date>.bpo-<issue-number>.<nonce>.rst``:

* ``<date>`` is today's date in ``YYYY-MM-DD`` format, e.g. ``2017-05-27``
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I actually emit YYYY-MM-DD-HH-MM-SS, both to further prevent collisions, and to ensure that entries are added in strict chronological order. It doesn't make a big difference, but I'd like it if you mentioned it. Changing the line to

  • <date> is today's date in YYYY-MM-DD or YYYY-MM-DD-HH-MM-DD format, e.g. 2017-05-27or 2017-05-27-08-22-35

* ``<issue-number>`` is the issue number the change is for, e.g. ``12345``
for ``bpo-12345``
* ``<nonce>`` is a unique, six-character string to guarantee the file name is
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's no length requirement for the nonce. I think even a zero-character string would work.

unique across branches, e.g. ``Yl4gI2``
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems like a problem for hand written files. Will the nonce remain the same in backported files? (I can take 'unique across branches' either way.)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How so? Just randomly bang on your keyboard and keep 6 letters. 😄

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or any number of letters, even zero. The nonce is really just there as a final arbiter to prevent filename collisions.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've now clarified this.


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::
So a file name may be
``Misc/NEWS.d/next/Library/2017-05-27.bpo-12345.Yl4gI2.rst``.

- bpo-15304: Fix warning message when `os.chdir()` fails inside
`test.support.temp_cwd()`. Patch by Chris Jerdonek.
A news file contents should be valid reStructuredText. An 80 character column
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bad English. Better: "The contents of a news file should be [...]"

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agreed

width should be used. The "default role"
(single backticks) in reST can be used to refer to objects in the documentation.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will they be ignored if there is no corresponding object in the docs?

Example news entry::
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd also like this to mention that, unlike in Misc/NEWS, news entries in Misc/NEWS.d shouldn't start with a -, shouldn't indent subsequent lines, and shouldn't start with Issue # or bpo-.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was wondering about that ;-)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clarified.


Fix warning message when `os.chdir()` fails inside
`test.support.temp_cwd()`. Patch by Chris Jerdonek.

(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 merging across branches 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.
**No editing should be done to ``Misc/NEWS``**. While this was the traditional
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, we decided to remove Misc/NEWS from the CPython tree. It'll be generated just-in-time as part of the release process so tarballs look the same. But it should no longer be checked in.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I dropped the mention.

way of adding news entries, it is now no longer necessary thanks to ``blurb``
and the use of individual files for each news entry. Only release managers
should ever edit ``Misc/NEWS``.


Commit Messages
Expand All @@ -235,10 +251,10 @@ it is common to simply paste the NEWS entry into the commit message. Here
is an example::

bpo-42: the spam module is now more spammy.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This contradicts Larry's comment above about not starting with 'bpo' or issue number.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is part of reST markup for a block literal so it actually doesn't when viewed as rendered HTML.


The spam module sporadically came up short on spam. This change
raises the amount of spam in the module by making it more spammy.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have never added spaces before acknowledgements before and I believe same was generally true. Unless the resulting News/changelog is formatted differently from before, blank lines might make it harder, not easier to read.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you mean the indent, that's once again because it's reST formatting for a literal block. If you mean the newline then I personally have always used it.

Regardless, I didn't change this format and so if you want to discuss the formatting of commit messages that belongs in a separate issue.

Thanks to Monty Python for the patch.

The first line or sentence is meant to be a dense, to-the-point explanation
Expand Down Expand Up @@ -272,7 +288,7 @@ Working with Git_

.. seealso::
:ref:`gitbootcamp`

As a core developer, the ability to push changes to the official Python
repositories means you have to be more careful with your workflow:

Expand All @@ -282,10 +298,10 @@ repositories means you have to be more careful with your workflow:
dedicated to maintenance of the work before the work gets integrated in the
main repository.

* You should not commit directly into the ``master`` branch, or any of the
* You should not commit directly into the ``master`` branch, or any of the
maintenance branches (``2.7``, ``3.5``, or ``3.6``). You should commit against
your own feature branch, and create a pull request.

It is recommended to keep a fork of the main repository around, as it allows simple
reversion of all local changes (even "committed" ones) if your local clone gets
into a state you aren't happy with.
Expand Down Expand Up @@ -410,7 +426,7 @@ new features. The other branches only receive bug fixes or security fixes.
Backporting Changes to an Older Version
---------------------------------------

When it is determined that a pull request needs to be backported into one or more of
When it is determined that a pull request needs to be backported into one or more of
the maintenance branches, a core developer can apply the labels ``needs backport to X.Y``
to the pull request.

Expand All @@ -421,13 +437,13 @@ on the ``master`` branch. To display the 10 most recent commit hashes and their
line of the commit message::

git log -10 --oneline

Prefix the backport pull request with the branch, for example::

[3.6] bpo-12345: Fix the Spam Module

Note that cherry_picker.py_ adds the branch prefix automatically.

Once the backport pull request has been created, remove the
``needs backport to X.Y`` label from the original pull request. (Only Core
Developers can apply labels to GitHub pull requests).
Expand Down
10 changes: 5 additions & 5 deletions developers.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@ This file is a running log of developers given commit privileges for Python.
The purpose is to provide some institutional memory of who was given access
and why.

The first entry starts in April 2005. In keeping with the style of Misc/NEWS,
newer entries should be added to the top. Entries should include the name
or initials of the project admin who made the change or granted access. The
procedure for adding or removing users is described in :ref:`altering-access`.
The first entry starts in April 2005. Newer entries should be added to the top.
Entries should include the name or initials of the project admin who made the
change or granted access. The procedure for adding or removing users is
described in :ref:`altering-access`.

Note, when giving new commit permissions, be sure to get a contributor agreement
from the committer. See https://www.python.org/psf/contrib/ for details. Commit
Expand All @@ -27,7 +27,7 @@ Permissions History

- Carol Willing was given push privileges on May 24, 2017 by Brett Cannon,
on his own recommendation.

- Mariatta Wijaya was given push privileges on January 27, 2017 by Brett Cannon,
on the recommendation of Raymond Hettinger.

Expand Down
2 changes: 1 addition & 1 deletion gitbootcamp.rst
A59F
Original file line number Diff line number Diff line change
Expand Up @@ -304,7 +304,7 @@ When a pull request submitter has enabled the `Allow edits from maintainers`_
option, Python Core Developers may decide to make any remaining edits needed
prior to merging themselves, rather than asking the submitter to do them. This
can be particularly appropriate when the remaining changes are bookkeeping
items like updating ``Misc/ACKS`` and ``Misc/NEWS``.
items like updating ``Misc/ACKS``.

.. _Allow edits from maintainers: https://help.github.com/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork/

Expand Down
2 changes: 1 addition & 1 deletion pullrequest.rst
Original file line number Diff line number Diff line change
Expand Up @@ -352,6 +352,6 @@ Crediting
---------

Non-trivial contributions are credited in the ``Misc/ACKS`` file (and, most
often, in a contribution's ``Misc/NEWS`` entry as well). You may be
often, in a contribution's news entry as well). You may be
asked to make these edits on the behalf of the core developer who
accepts your pull request.
0