Release procedure#

This page provides an overview of how euclid_rag releases are made. This information is primarily useful for maintainers.

Releases are largely automated through GitHub Actions (see the ci.yaml workflow file for details). When a semantic version tag is pushed to GitHub, euclid_rag is automatically released on GitHub with that version. Documentation is built and published for each version (see Euclid RAG Documentation).

Regular releases#

Releases are made from the main branch after changes are merged. You can release a new major version (X.0.0), a new minor version (X.Y.0), or a new patch version (X.Y.Z). To patch an earlier version, see Backport releases.

Release tags use semantic versioning according to the PEP 440 spec.

1. Change log and documentation#

Changelog messages are collected using scriv. See Updating the change log in the Developer Guide for more.

Before release, gather the changelog fragments in changelog.d by running:

scriv collect --version X.Y.Z

This creates a full changelog entry in CHANGELOG.md and removes the fragments.

Review, edit, and commit the updated changelog. Create a PR, get it merged, and then proceed to tagging the release.

2. GitHub release and tag#

Use GitHub Releases to publish the new version.

  • Tag from the correct branch (usually main).

  • Use semantic versioning like X.Y.Z (no v prefix).

  • Set the release name to the version string.

  • Use the changelog content in the release notes.

Tags must follow PEP 440, since version metadata is derived using setuptools_scm.

Once tagged, the GitHub Actions workflow will create the release and update the documentation site.

Backport releases#

To patch older major/minor versions, use a release branch named after the X.Y version.

Creating a release branch#

If a release branch does not yet exist:

git checkout X.Y.Z
git checkout -b X.Y
git push -u origin X.Y

Developing on a release branch#

Use the release branch for all patch-level updates. Backport changes from main using git cherry-pick if needed.

Releasing from a release branch#

Follow the same process as a regular release, but tag from the release branch instead of main. ci.yaml will handle creating the GitHub release and updating the documentation.