releasing

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

Important: This tooling is built for foundata's release process(es). You are welcome to use it but Pull Requests to adapt our toolset to different release policies or processes are out of scope.

Components and tools:

• release: command that covers the error-prone steps around a release: preparing repository Markdown for package indexes, and, as the package grows, version sites, changelogs, artifacts, tags and post-publish verification. 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

Project-aware commands 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 for a Python project is in Releasing a Python package.

Every command exits with 0 on success, 1 when a check or operation fails and 2 on invalid usage. Diagnostics go to stderr; stdout carries only generated output.

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.