Continuous Integration¶

Cosmic Ray uses GitHub Actions for continuous integration and release automation.

On every push and pull request, the Run tests workflow runs linting and tests across supported Python versions.

Release publishing is managed by the manually triggered release workflow:

Select a ref (branch/tag/SHA) and bump component (major/minor/patch).
The workflow computes the next release/vX.Y.Z tag.
It checks out the selected commit and computes release metadata.
It creates/pushes the tag, builds distributions, and uploads them to PyPI.
It generates GitHub Release notes using git-cliff from commits since the previous release tag.
Version metadata comes from the release tag through hatch-vcs.

Releasing a new version¶

Releases use dynamic VCS-based versioning. pyproject.toml does not contain a static project.version value.

Option 1: Use GitHub Actions (recommended)¶

From the GitHub UI, run the release workflow manually:

Open the release workflow.
Choose part (patch, minor, or major).
Choose ref (defaults to master).
Start the workflow.

The workflow computes the next release tag automatically and publishes from the selected release ref.

Option 2: Use the helper script (local/manual fallback)¶

From a clean working tree on the commit you want to release:

tools/release.py patch

Use tools/release.py --help for options such as --dry-run, --from-ref, --next-version-only, --no-push, and --remote.

Development versions¶

Outside a release tag, development builds use VCS-derived versions from hatch-vcs/setuptools-scm (for example 8.5.1.dev3+g<hash>), making it obvious the build is not a final release.

Changelog with git-cliff¶

Changelog generation is based on git-cliff and Conventional Commits.

Configuration lives in cliff.toml and is tuned for release tags named release/vX.Y.Z.

Typical usage:

# Generate or refresh a local changelog from tags/commits
git cliff --config cliff.toml -o CHANGELOG.md

# Preview unreleased notes without writing to disk
git cliff --config cliff.toml --unreleased

The release workflow uses git-cliff --latest --strip header to generate the GitHub Release body directly during CI; no changelog commit is created.

Conventional commit types such as feat and fix are grouped into changelog sections (Added, Fixed, and so on). Non-conventional commits are filtered out.

Releasing from historical commits¶

GitHub manual workflow dispatch runs on branch or tag refs, not arbitrary commit SHAs. To release from a historical point, create a branch at that commit first, then run the normal release process from that branch.