Skip to main content

Command-line tool to manage CPython Misc/NEWS.d entries.

Project description

blurb

PyPI version GitHub Actions Codecov Python discussions

Overview

blurb is a tool designed to rid CPython core development of the scourge of Misc/NEWS conflicts.

The core concept: split Misc/NEWS into many separate files that, when concatenated back together in sorted order, reconstitute the original Misc/NEWS file. After that, Misc/NEWS could be deleted from the CPython repo and thereafter rendered on demand (e.g. when building a release). When committing a change to CPython, the commit process 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 install blurb from PyPI using pip. Alternatively, simply add blurb to a directory on your path.

Files used by blurb

blurb uses a new directory tree called Misc/NEWS.d. Everything it does is in there, except for possibly modifying Misc/NEWS.

Under Misc/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.

  • The next directory, which contains subdirectories representing the various Misc/NEWS categories. Inside these subdirectories are more .rst files with long, uninteresting, computer-generated names. Example: Misc/NEWS.d/next/Library/2017-05-04-12-24-06.gh-issue-25458.Yl4gI2.rst

blurb subcommands

Like many modern utilities, blurb has only one executable (called blurb), but provides a diverse set of functionality through subcommands. The subcommand is the first argument specified on the command-line.

If you're a CPython contributor, you probably don't need to use anything except blurb add — and you don't even need to specify the add part. (If no subcommand is specified, blurb assumes you meant blurb add.) The other commands are only expected to be useful for CPython release managers.

blurb help

blurb is self-documenting through the blurb 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 a third argument, it prints help on that subcommand (e.g. blurb help release).

blurb add

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

The template for the blurb 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 the end of the .. gh-issue: line.

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

  • Finally, go to the end of the file, and enter your NEWS entry. This should be a single paragraph of English text using simple reST markup.

When blurb add gets a valid entry, it writes it to a file with the following format:

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

For example, a file added by blurb 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 as YYYY-MM-DD-hh-mm-ss.

<nonce> is a hopefully-unique string of characters meant to prevent filename collisions. blurb creates this by computing the 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 in Misc/NEWS will be sorted by time.

  • It is unthinkably unlikely that there'll be a conflict between 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

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

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

Splitting and recombining the existing Misc/NEWS file doesn't recreate the previous Misc/NEWS exactly. This is because Misc/NEWS never used a consistent ordering for the "sections" inside each release, whereas blurb merge has 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 uses gh-issue-<n>: to specify issue numbers at the beginnings of entries, wheras the legacy approach to Misc/NEWS required using Issue #<n>:.

blurb release

blurb release is used by the release manager as part of the 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 from the Misc/NEWS.d/next directory into Misc/NEWS.d/<version>.rst.
  • Runs blurb merge to produce an updated Misc/NEWS file.

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

The "next" directory

You may have noticed that blurb add adds news entries to a directory called next, and blurb release combines those news entries into a single file named with the version. Why is 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-day exploit and we need to release an emergency 3.6.5 final, we don't have to fix up a bunch of metadata.

Second, it means that if you cherry-pick a commit forward or backwards, you automatically pick up the NEWS entry too. You don't need to touch anything up — the system will already do the right thing. If NEWS entries were already written to the final version directory, you'd have to move those around as part of the cherry-picking process.

Copyright

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

Changelog

See CHANGELOG.md.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

blurb-2.0.0.tar.gz (24.7 kB view details)

Uploaded Source

Built Distribution

blurb-2.0.0-py3-none-any.whl (18.9 kB view details)

Uploaded Python 3

File details

Details for the file blurb-2.0.0.tar.gz.

File metadata

  • Download URL: blurb-2.0.0.tar.gz
  • Upload date:
  • Size: 24.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.0.1 CPython/3.12.8

File hashes

Hashes for blurb-2.0.0.tar.gz
Algorithm Hash digest
SHA256 c78d8114294225a4f7a2eabba6e05d36a6a50e45ba9f5a41afabc198350038e0
MD5 610dcb56c5851a8db57c6e3d3cc95475
BLAKE2b-256 d7828597d891f4b03f3eaefcb4213a811643d558350cac9a69864d127832cc4f

See more details on using hashes here.

Provenance

The following attestation bundles were made for blurb-2.0.0.tar.gz:

Publisher: release.yml on python/blurb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file blurb-2.0.0-py3-none-any.whl.

File metadata

  • Download URL: blurb-2.0.0-py3-none-any.whl
  • Upload date:
  • Size: 18.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.0.1 CPython/3.12.8

File hashes

Hashes for blurb-2.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f6d0e858dbe94765f6a89b8228217ffdb9c19cff08fc8f2c3153954846d31aa1
MD5 343e39fc31346a3c1e9715f5f5e449ff
BLAKE2b-256 b403374bd9e31b58e8a8e5dc65cc3f68ca7cdd716c32b5e5dcb0e1b76bb75b4a

See more details on using hashes here.

Provenance

The following attestation bundles were made for blurb-2.0.0-py3-none-any.whl:

Publisher: release.yml on python/blurb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page