<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<p>
</p>
<div class="moz-text-html" lang="x-unicode"> <br>
<br>
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.)<br>
<br>
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.<br>
<br>
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.<br>
<blockquote><a class="moz-txt-link-freetext"
href="https://github.com/python/core-workflow/tree/master/blurb">https://github.com/python/core-workflow/tree/master/blurb</a><br>
</blockquote>
<br>
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:<br>
<ul>
<li>the bugs.python.org or "bpo" issue number,</li>
<li>what "section" of Misc/NEWS this entry should go in (by
uncommenting the correct line), and</li>
<li>the text of the Misc/NEWS entry, in ReST format.<br>
</li>
</ul>
You save and exit and you're done. blurb even stages the
Misc/NEWS entry in git for you!<br>
<br>
<br>
Behind the scenes, blurb writes your information here:<br>
<blockquote>Misc/NEWS.d/next/<section-name>/<filename><br>
</blockquote>
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.<br>
<br>
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.<br>
<br>
<br>
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!<br>
<br>
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.<br>
<br>
<br>
You can install blurb from pip:<br>
<blockquote>% pip3.6 install blurb<br>
</blockquote>
In fact--please do!<br>
<br>
<br>
<i>/arry</i><br>
</div>
</body>
</html>