[Python-Dev] New workflow change: Welcome to blurb

Antoine Pitrou solipsis at pitrou.net
Sat Jun 24 13:06:31 EDT 2017


I have just used blurb on https://github.com/python/cpython/pull/2010
and it was absolutely painless.  Thank you!

One minor thing: `make patchcheck` doesn't know to examine the NEWS.d
directory when checking for NEWS entries.



On Fri, 23 Jun 2017 20:24:05 -0700
Larry Hastings <larry at hastings.org> wrote:
> One minor but ongoing problem we've had in CPython core development has 
> been the mess of updating Misc/NEWS.  Day-to-day developers may have a 
> conflict if they lose a push race, which means a little editing.  You'll 
> have a similar, if slightly worse, problem when cherry-picking a fix 
> between versions.  Worst of all used to be the manual merges necessary 
> after cutting a release--this was the bane of a CPython release 
> manager's existence.  (Though the new git-based workflow may have 
> obviated the worst of this.)
> The real problem is that we have one central file that everybody 
> continually edits in a haphazard way.  We aren't actually editing the 
> same information, we aren't actually changing the same lines. But our 
> revision control systems and diff algorithms don't understand the 
> structure of Misc/NEWS and so they get confused. And for what? It's not 
> like there's a tremendous benefit to having this central file everyone's 
> fighting over.
> We've been talking about addressing this for years.  Fixing this was one 
> of the goals of the new workflow.  And finally, as of right now, the 
> future is here.  Ladies and gentlemen, I present: blurb.
>     https://github.com/python/core-workflow/tree/master/blurb
> blurb is an interactive command-line tool that helps you write Misc/NEWS 
> entries.  You simply run blurb from anywhere inside a CPython repo.  
> blurb runs an editor for you with a template open. You fill in these 
> three pieces of information:
>   * the bugs.python.org or "bpo" issue number,
>   * what "section" of Misc/NEWS this entry should go in (by uncommenting
>     the correct line), and
>   * the text of the Misc/NEWS entry, in ReST format.
> You save and exit and you're done.  blurb even stages the Misc/NEWS 
> entry in git for you!
> Behind the scenes, blurb writes your information here:
>     Misc/NEWS.d/next/<section-name>/<filename>
> The "<section-name>" is the name of the section in Misc/NEWS where your 
> entry should go.  <filename> contains the current date and time, the bpo 
> number, and a nonce to prevent collisions.
> These "next" files get merged together into a single aggregate .rst file 
> by the release manager when cutting a release (using "blurb release").  
> One nice feature of this approach: when you cherry-pick a change, its 
> Misc/NEWS entry in "next" gets cherry-picked along with it.
> One important change: Misc/NEWS will no longer be checked in. It'll 
> still be present in CPython tarballs; it will be generated by the 
> release manager as part of cutting a release.  But as a repository of 
> information, it's been superseded by the various blurb data files.  And 
> by regenerating it from data files, we ensure that we'll never ever have 
> a Misc/NEWS conflict ever again!
> The plan is to leave Misc/NEWS in the CPython repo for maybe another 
> week, to let the current crop of PRs get merged.  But new work should 
> switch to using blurb immediately.
> You can install blurb from pip:
>     % pip3.6 install blurb
> In fact--please do!
> //arry/

More information about the Python-Dev mailing list