Repository files navigation

blurb is a tool designed to rid CPython core developmentof the scourge ofMisc/NEWS conflicts.

The core concept: splitMisc/NEWS into manyseparate files that, when concatenated back togetherin sorted order, reconstitute the originalMisc/NEWS file.After that,Misc/NEWS could be deleted from the CPythonrepo and thereafter rendered on demand (e.g. when buildinga release). When committing a change to CPython, the commitprocess will write out a new file that sorts into the correct place,using a filename unlikely to have a merge conflict.

blurb is a single command with a number of subcommands.It's designed to be run inside a valid CPython (Git) repo,and automatically uses the correct file paths.

You can installblurb from PyPI usingpip. Alternatively,simply addblurb to a directory on your path.

blurb uses a new directory tree calledMisc/NEWS.d.Everything it does is in there, except for possiblymodifyingMisc/NEWS.

UnderMisc/NEWS.d you'll find the following:

• A single file for all news entries per previous revision,named for the exact version number, with the extension.rst.Example:Misc/NEWS.d/3.6.0b2.rst.

• Thenext directory, which contains subdirectories representingthe variousMisc/NEWS categories. Inside these subdirectoriesare more.rst files with long, uninteresting, computer-generatednames. Example:Misc/NEWS.d/next/Library/2017-05-04-12-24-06.gh-issue-25458.Yl4gI2.rst

Like many modern utilities,blurb has only one executable(calledblurb), but provides a diverse set of functionalitythrough subcommands. The subcommand is the first argument specifiedon the command-line.

If you're a CPython contributor, you probably don't need to useanything exceptblurb add — and you don't even need to specifytheadd part.(If no subcommand is specified,blurb assumes you meantblurb add.)The other commands are only expected to be useful for CPython releasemanagers.

blurb is self-documenting through theblurb help subcommand.Run without any further arguments, it prints a list of all subcommands,with a one-line summary of the functionality of each. Run with athird argument, it prints help on that subcommand (e.g.blurb help release).

blurb add adds a newMisc/NEWS entry for you.It opens a text editor on a template; you edit thefile, save, and exit.blurb then stores the filein the correct place, and stages it in Git for you.

The template for theblurb add message looks like this:

## Please enter the relevant GitHub issue number here:#.. gh-issue:## Uncomment one of these "section:" lines to specify which section# this entry should go in in Misc/NEWS.##.. section: Security#.. section: Core and Builtins#.. section: Library#.. section: Documentation#.. section: Tests#.. section: Build#.. section: Windows#.. section: macOS#.. section: IDLE#.. section: Tools/Demos#.. section: C API# Write your Misc/NEWS entry below.  It should be a simple ReST paragraph.# Don't start with "- Issue #<n>: " or "- gh-issue<n>: " or that sort of stuff.###########################################################################

Here's how you interact with the file:

• Add the GitHub issue number for this commit to theend of the.. gh-issue: line.

• Uncomment the line with the relevantMisc/NEWS section for this entry.For example, if this should go in theLibrary section, uncommentthe line reading#.. section: Library. To uncomment, just deletethe# at the front of the line.

• Finally, go to the end of the file, and enter yourNEWS entry.This should be a single paragraph of English text usingsimple reST markup.

Whenblurb add gets a valid entry, it writes it to a filewith the following format:

Misc/NEWS.d/next/<section>/<datetime>.gh-issue-<issue_number>.<nonce>.rst

For example, a file added byblurb add might look like this::

Misc/NEWS.d/next/Library/2017-05-04-12-24-06.gh-issue-25458.Yl4gI2.rst

<section> is the section provided in the commit message.

<datetime> is the current UTC time, formatted asYYYY-MM-DD-hh-mm-ss.

<nonce> is a hopefully-unique string of characters meant toprevent filename collisions.blurb creates this by computingthe MD5 hash of the text, converting it to base64 (using the"urlsafe" alphabet), and taking the first 6 characters of that.

This filename ensures several things:

• All entries inMisc/NEWS will be sorted by time.

• It is unthinkably unlikely that there'll be a conflictbetween the filenames generated for two developers committing,even if they commit in at the exact same second.

Finally,blurb add stages the file in git for you.

blurb merge recombines all the files in theMisc/NEWS.d tree back into a singleNEWS file.

blurb merge accepts only a single command-line argument:the file to write to. By default, it writes toMisc/NEWS (relative to the root of your CPython checkout).

Splitting and recombining the existingMisc/NEWS filedoesn't recreate the previousMisc/NEWS exactly. Thisis becauseMisc/NEWS never used a consistent orderingfor the "sections" inside each release, whereasblurb mergehas a hard-coded preferred ordering for the sections. Also,blurb aggressively reflows paragraphs to < 78 columns,wheras the original hand-edited file occasionally had lines >80 columns. Finally,blurb strictly usesgh-issue-<n>: tospecify issue numbers at the beginnings of entries, wherasthe legacy approach toMisc/NEWS required usingIssue #<n>:.

blurb release is used by the release manager as part ofthe CPython release process. It takes exactly one argument,the name of the version being released.

Here's what it does under the hood:

• Combines all recently-added NEWS entries fromtheMisc/NEWS.d/next directory intoMisc/NEWS.d/<version>.rst.
• Runsblurb merge to produce an updatedMisc/NEWS file.

One hidden feature: if the version specified is.,blurb releaseuses the name of the directory CPython is checked out to.(When making a release I generally name the directory after theversion I'm releasing, and using this shortcut saves me some typing.)

You may have noticed thatblurb add adds news entries toa directory callednext, andblurb release combines thosenews entries into a single file named with the version. Whyis that?

First, it makes naming the next version a late-binding decision.If we are currently working on 3.6.5rc1, but there's a zero-dayexploit and we need to release an emergency 3.6.5 final, we don'thave to fix up a bunch of metadata.

Second, it means that if you cherry-pick a commit forward orbackwards, you automatically pick up theNEWS entry too. Youdon't need to touch anything up — the system will already dothe right thing. IfNEWS entries were already written to thefinal version directory, you'd have to move those around aspart of the cherry-picking process.

blurb is Copyright 2015-2018 by Larry Hastings.Licensed to the PSF under a contributor agreement.

SeeCHANGELOG.md.