releasing (helpers and tooling for software releases)

Release helpers for projects that publish from a Git-tracked source tree.

Important: This tooling is built for foundata's own release processes. You are welcome to use it but requests to adapt our toolset to different release policies or processes are out of scope.

Components and tools:

• release: one command for error-prone steps around a release: version sites, changelogs, artifacts, tags, the push, the upload, the forge's release entry, post-publish verification, and the repository Markdown a package index needs. Each step is one subcommand; the order of steps stays in each project's own procedure.

Installation

Add it to a development dependency group of the project that releases:

[dependency-groups]
dev = ["releasing"]

Run it without installing anything into the project:

uvx --from git+https://github.com/foundata/releasing release --help

Python 3.11 to 3.14 are supported. The minimum is 3.11 rather than the 3.12 baseline of the foundata Python guide because the package is a development dependency of projects that target Debian 12, which ships Python 3.11.

Commands

release

Project-aware subcommands read the release declaration, one table in pyproject.toml or releasing.toml. Markdown preparation and explicit-version artifact operations also work independently; see The release declaration.

• release config check: validate the declaration and every file it names, and print the effective values.
• release version check and release version bump: every declared version site, the lockfile, lockstep pins and the tag agree, or move them all to a new version. See Version sites.
• release changelog check, show and release: Keep a Changelog sections, dates and links are consistent, one section is printed for a release description, or the unreleased entries become a dated section. See Changelog sections.
• release build: export a committed revision, prepare the index Markdown inside that export, build, check and record a manifest. See Building from an exported revision.
• release tag create, check and delete: a guarded annotated tag, and a deletion that stays legal only while no release exists. See Release tags.
• release status: report which steps of a release are done, pending or broken. See Where a release stands.
• release push: publish the release branch and its tag together, after re-checking both. See Publishing the branch and the tag.
• release publish: upload exactly the files a manifest names, refusing any other file beside them. See Uploading what was validated.
• release forge release-create: create the forge's release entry from the changelog and the manifest. See The forge's release entry.
• release verify: the index serves the validated files, an isolated install reports the version and the forge reports the tag as latest. See Verifying a published release.
• release artifacts check, manifest and verify: distributions carry the right version, a description without relative links and no litter; their digests are recorded and later compared. See Artifacts.
• release markdown prepare: rewrite repository-relative link and image destinations to absolute URLs without reformatting the document. See Preparing Markdown for package indexes.

The end-to-end order is in Releasing a Python package and Releasing an Ansible collection.

Output

Every command sends its result to stdout and its progress to stderr, so output can be redirected without knowing which command is in hand.

Stdout carries what the command produced and nothing else: the tag it created, the files it built, the changelog section, the manifest JSON, the report. A check writes nothing there and communicates its result through the exit status.

Stderr carries what happened on the way: what is being done, every command that changed something, and every request to a forge or an index.

$ release tag create 2.2.0 --manifest ../dist-2.2.0/artifacts.json
» Found artifacts built from 41db3420c2d6 in the manifest
» Verified the working tree is clean
» Exporting 41db3420c2d6 into a temporary directory
$ git -C /home/example/project archive --format=tar 41db3420c2d6...
» Checking version sites, lockfile, pins and changelog in the export
» GET https://api.github.com/repos/foundata/releasing/releases/tags/v2.2.0 → 404
$ git -C /home/example/project tag -a v2.2.0 41db3420c2d6 -m 'version 2.2.0'
v2.2.0

--quiet (-q), accepted before or after the command, keeps stdout and drops the progress on stderr. It never suppresses an error. 2>/dev/null does the same, and 2>&1 | tee release.log keeps both together.

Every command that changes something accepts --dry-run: it reports what it would do, marks the commands it would run, and changes nothing. A command that only reads does not offer the flag.

Every command exits with 0 on success, 1 when a check or operation fails and 2 on invalid usage.

Releasing this package

releasing releases itself with its own commands. The procedure is in the development guide; the recipe it follows is Releasing a Python package. The declaration is the [tool.releasing] table in pyproject.toml.

Development

See the development guide for the checks, the test layout and the corpus maintenance.

Licensing, copyright

Copyright (c) 2026 foundata GmbH (https://foundata.com)

This project is licensed under the GNU General Public License v3.0 or later (SPDX-License-Identifier: GPL-3.0-or-later), see LICENSES/GPL-3.0-or-later.txt for the full text.

The REUSE.toml file provides detailed licensing and copyright information in a human- and machine-readable format. This includes parts that may be subject to different licensing or usage terms, such as third-party components. The repository conforms to the REUSE specification. You can use reuse spdx to create a SPDX software bill of materials (SBOM).

Author information

This project was created and is maintained by foundata.