[python-committers] Workflow change reminder: The Blurb Has Landed

[Larry Hastings]

Yesterday I "blurbified" the 2.7, 3.6, and master branches in CPython.  
It's finally official: all* branches have now been "blurbified".  This 
means that Misc/NEWS is no longer present in any of CPython's active 
branches.  Instead, Misc/NEWS has been broken up into a zillion little 
files in the new Misc/NEWS.d directory tree. (Misc/NEWS can be 
reconstituted consistently from this directory tree.)  This banishes 
forever the annoying problem of Misc/NEWS merge conflicts when you 
attempt to merge a pull request, when release managers create a release, 
etc.

We announced "blurb" a month or two back, and you should already be 
creating your news entries in Misc/NEWS.d.  But just in case, here's a 
quick refresher.

The core-workflow team has created a tool called "blurb" that makes it 
easy to create a news entry for a commit.  It's easy to install and use.

You can install it with:

    python3 -m pip install blurb

It requires Python 3.5 or newer.  (Sorry, it can't get backported to 3.4 
without fixing a bug in "re"... and 3.4 is closed for bugfixes.)

To create a news entry, just run blurb from anywhere inside your CPython 
repo.  On POSIX systems just make sure "blurb" is on your path, then 
simply run "blurb".  On Windows the recommended method is "python3 -m 
blurb".

When you run blurb, it'll guide you through creating a news entry. It'll 
pop open an editor window on a template.  Just modify the template as 
needed, write your news entry at the bottom, and save and exit.  blurb 
will write out your news entry as a uniquely-named file in 
Misc/NEWS.d--and even stage it for you in "git"!

If for some reason you want to create news entries by hand, or if you 
just want more information, please see the Dev Guide:

    https://devguide.python.org/committing/#what-s-new-and-news-entries

and the documentation for blurb on PyPI:

     https://pypi.org/project/blurb/

The migration to Misc/NEWS.d and blurb has a few other implications:

 1. Existing pending PRs or patches with Misc/NEWS entries will need to
    be updated to generate the entry with blurb.  (Again, there really
    shouldn't /be/ any by this point.)
 2. If you want to read a branch's NEWS entries in a convenient format,
    simply use "blurb merge" to produce a temporary NEWS file.  (But
    don't check it in!)  See the blurb documentation.
 3. As part of the release process, release managers now use blurb to
    merge all the individual NEWS.d/next files into a single NEWS.d file
    for that version.  They'll also build a traditional monolithic
    Misc/NEWS included in the release's source tarball (but this won't
    get checked in).
 4. If you're building 3.x docs from a cpython git repo, you'll now need
    to have blurb installed.  You can use the "make venv" recipe in
    Doc/Makefile to create a python3 venv with blurb and sphinx.


Happy blurbing!


/arry

* All except 3.3.  Ned Deily has taken over as release manager of 3.3, 
and he thinks we shouldn't bother with blurbifying that branch--it'll 
reach end-of-life in mere weeks, and we're only going to make one more 
release of it, and it gets very little work done these days.

p.s. Thanks to Ned Deily who originally wrote this email, which I hacked 
up and sent.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-committers/attachments/20170905/de8586b9/attachment.html>