release.py

Overview

The `release.py` file provides a set of command-line driven utilities designed to automate and streamline the software release process for the project. Its main functionalities include generating release announcement documentation, regenerating example outputs in the docs, fixing code formatting, checking documentation links, and preparing a full pre-release cycle including git tagging and committing.

This file primarily interacts with:

• Git, to query commit metadata and manage release tags.

• Documentation files, to generate release announcement entries and update changelogs.

• External tools such as tox, pre-commit, and towncrier for testing, formatting, and changelog generation.

• Sphinx documentation builder to verify link integrity.

By encapsulating these tasks, `release.py` helps maintain release consistency and automation, reducing manual errors and effort.

Detailed Descriptions

Functions

announce(version: str, template_name: str, doc_version: str) -> None

**Purpose:** Generates a new release announcement file in the documentation based on a provided template. It collects the list of authors and co-authors from git commit history since the last version tag, formats the contributors list, and inserts it into the announcement file.

**Parameters:**

• version (str): The new release version string (e.g., "1.2.0").

• template_name (str): Filename of the release announcement template (relative to this script's directory).

• doc_version (str): Documentation version string to link to in the announcement (commonly used for prereleases).

**Returns:**

• None

**Usage Example:**

announce("1.2.0", "release_template.rst", "1.2")

**Implementation details:**

• Uses git commands like git describe --abbrev=0 --tags to find the last version tag.

• Extracts authors and "Co-authored-by" trailers from commits between the last tag and HEAD.

• Filters out bots and duplicates, sorts contributors alphabetically.

• Reads the announcement template file and formats it with version, contributors, and doc_version.

• Writes the announcement file to ../doc/en/announce/release-{version}.rst.

• Updates the announcement index file (index.rst) to include the new release entry.

• Stages the new announcement file via git add.

regen(version: str) -> None

**Purpose:** Invokes the `tox` environment `regen` to update documentation examples and pytest outputs, ensuring docs reflect the current code state.

**Parameters:**

• version (str): Version string passed as an environment variable to influence pytest behavior.

**Returns:**

• None

**Usage Example:**

regen("1.2.0")

**Implementation details:**

• Runs tox -e regen with an environment variable SETUPTOOLS_SCM_PRETEND_VERSION_FOR_PYTEST set to the version.

• Prints informative status messages.

fix_formatting() -> None

**Purpose:** Runs `pre-commit` hooks on all files to fix code formatting and linting issues automatically.

**Returns:**

• None

**Usage Example:**

fix_formatting()

**Implementation details:**

• Calls pre-commit run --all-files.

• Uses call() (does not raise on failure).

check_links() -> None

**Purpose:** Runs Sphinx documentation build with a special environment to verify that all links in the docs are valid.

**Returns:**

• None

**Usage Example:**

check_links()

**Implementation details:**

• Runs tox -e docs-checklinks which is assumed to run Sphinx with link checking enabled.

• Uses check_call() to raise if link checking fails.

pre_release(version: str, template_name: str, doc_version: str, *, skip_check_links: bool) -> None

**Purpose:** Runs a full pre-release workflow that:

• Generates release announcement.

• Regenerates docs examples.

• Updates changelog.

• Fixes formatting.

• Optionally checks documentation links.

• Commits all changes with a message referencing the release version.

**Parameters:**

• version (str): Release version string.

• template_name (str): Template filename for the announcement.

• doc_version (str): Documentation version string.

• skip_check_links (bool, keyword-only): If True, skips the link-checking step.

**Returns:**

• None

**Usage Example:**

pre_release("1.2.0", "release_template.rst", "1.2", skip_check_links=False)

**Implementation details:**

• Calls announce(), regen(), changelog(write_out=True), fix_formatting().

• Calls check_links() if not skipped.

• Commits all changes with git.

• Prints success messages and instructions to push branch and open a PR.

changelog(version: str, write_out: bool = False) -> None

**Purpose:** Generates or drafts changelog entries using `towncrier`.

**Parameters:**

• version (str): Release version string.

• write_out (bool, optional): If True, writes out the changelog; if False, generates a draft.

**Returns:**

• None

**Usage Example:**

changelog("1.2.0", write_out=True)

**Implementation details:**

• Calls towncrier build --yes --version {version} with optional --draft flag.

main() -> None

**Purpose:** Entry point for the script when run from the command line.

**Returns:**

• None

**Usage:** From the shell:

python release.py 1.2.0 release_template.rst 1.2 --skip-check-links

**Implementation details:**

• Initializes colorama for colored terminal output.

• Parses command-line arguments:

  • version: release version.

  • template_name: announcement template filename.

  • doc_version: documentation version.

  • --skip-check-links: optional flag.

• Calls pre_release() with parsed options.

Implementation Highlights

• The script heavily relies on git commands to extract metadata for releases.

• Uses subprocess calls to external tools (tox, pre-commit, towncrier) for various build and validation steps.

• Uses colorama to print colored informational messages to the terminal.

• Employs Python 3.8+ syntax features like the walrus operator (:=) in regex matching.

• Carefully manages file paths relative to the script location via Path(__file__).parent.

• Updates documentation files in place and stages them for git commits automatically.

• Modular functions allow selective execution of release tasks.

Interaction with Other System Components

• Git Repository:
  Extracts version tags, commit authors, co-authors; stages and commits release-related files.

• Documentation Source Files:
  Reads templates and writes release announcement .rst files, updates announcement index.

• External Tooling:

  • tox for running environment-specific commands (e.g., regenerating docs, checking links).

  • pre-commit for linting and formatting fixes.

  • towncrier for changelog generation.

• Sphinx Documentation:
  Link checking is done via a tox environment that runs Sphinx with link validation.

Visual Diagram

flowchart TD
    main --> pre_release
    pre_release --> announce
    pre_release --> regen
    pre_release --> changelog
    pre_release --> fix_formatting
    pre_release --> check_links
    announce --> git_describe[git describe]
    announce --> git_log_authors[git log authors]
    announce --> git_log_coauthors[git log co-authors]
    announce --> read_template[Read Template File]
    announce --> write_announcement[Write release-{version}.rst]
    announce --> update_index[Update index.rst]
    regen --> tox_regen[tox -e regen]
    fix_formatting --> pre_commit[pre-commit run --all-files]
    check_links --> tox_checklinks[tox -e docs-checklinks]
    changelog --> towncrier_build[towncrier build]
    pre_release --> git_commit[git commit -a -m "Prepare release version"]

Summary

The `release.py` file is a utility script designed to automate the routine tasks involved in preparing a software release, including generating documentation announcements, updating changelogs, ensuring formatting standards, checking documentation integrity, and managing git commits and tags. The script integrates tightly with git, documentation files, and external tools to provide a seamless pre-release workflow driven by a simple command-line interface.