Release process#

This guide is for maintainers preparing a release. Contributors can follow Contributing without performing these steps.

Prepare the release commit#

  1. Review the changes to include and check their test, lint, and validation results. Build the documentation locally using Building and editing the docs.

  2. Set __version__ in zrad/__init__.py to the intended release version, following the conventions below. Package metadata and documentation read this value; the release tag does not change it automatically.

  3. Commit the version and release-related documentation changes. Confirm the intended commit contains the code and version you want to publish.

Version conventions#

Z-Rad uses date-based, PEP 440-compatible versions:

Version examples#

Type

Format

Example

Stable

YY.M.PATCH

26.5.0 for the first May 2026 release; 26.5.1 for a subsequent patch.

Development

YY.M.PATCH.devN

26.6.0.dev0 for development toward the June 2026 release.

Keep the patch component, including .0 for the first release of a month. Use .dev0 for the normal in-repository development version. Write the month without leading zeroes: 26.5.0, not 26.05.0.

Publish the GitHub release#

Create or select the release tag on the intended commit and prepare the release notes. Check that the tag and notes identify the package version in that commit. Publish the GitHub release when it is ready for distribution.

Publication triggers both workflows below; they do not wait for one another. Their trigger is release: published, with no stable-release-only condition. Do not assume marking a release as a prerelease suppresses publication jobs.

Package publication#

.github/workflows/publish.yml uses Python 3.12, installs build and twine, runs python -m build, and uploads dist/* to PyPI with Twine. It reads the repository secrets PYPI_USERNAME and PYPI_PASSWORD for upload credentials.

Desktop application builds#

.github/workflows/release-executables.yml uses generate_executable.py and PyInstaller to build and attach:

  • z-rad-<release-tag>-windows.exe from windows-latest

  • z-rad-<release-tag>-macos-arm64.zip from macos-latest

The macOS ZIP contains an Apple Silicon Z-Rad.app bundle. Intel macOS binaries are not produced. The app is unsigned and unnotarized, so Gatekeeper warnings are expected. Adding signing and notarization requires Apple Developer credentials and a change to the release workflow.

Verify the published artifacts#

Check both workflow runs after publication. Verify that PyPI shows the intended package version and that the GitHub release contains both desktop assets. A successful package upload does not establish that the executable builds passed.

As a release check, install the published package in a fresh environment and confirm its version and imports. Download the desktop assets and check that they launch on their target platforms. If a job fails, inspect its logs and the artifacts already published before deciding how to recover; publication can succeed for one artifact while another fails.