Release Process

This document describes the release process for oak-ci. All releases are cut directly from main (trunk-based development).

Version numbering

OAK uses PEP 440 version strings. Tags must use PEP 440-native pre-release suffixes — SemVer-style suffixes (e.g. v0.6.0-beta.1) are not supported because hatch-vcs does not map them to valid PEP 440 versions.

Release type	Tag format	PyPI version	Example
Stable	vX.Y.Z	X.Y.Z	v0.5.0
Beta	vX.Y.ZbN	X.Y.ZbN	v0.6.0b1
Release candidate	vX.Y.ZrcN	X.Y.ZrcN	v0.6.0rc1
Alpha	vX.Y.ZaN	X.Y.ZaN	v0.6.0a1
TestPyPI only	vX.Y.Z-testpypi.N	X.Y.Z.postN.dev0	v0.5.0-testpypi.1

Release flows

Stable release

Tag vX.Y.Z on main. The workflow:

1. Builds the Python wheel and sdist.
2. Creates a GitHub Release (marked latest) with commit log and stable install instructions.
3. Publishes to PyPI.
4. Triggers update-formula.yml in goondocks-co/homebrew-oak to update Formula/oak-ci.rb.

git tag v0.5.0
git push origin v0.5.0

User install:

brew install goondocks-co/oak/oak-ci
pipx install oak-ci --python python3.13
uv tool install oak-ci --python python3.13

---

Pre-release (beta, RC, alpha)

Tag vX.Y.ZbN (or rcN, aN) on main. The workflow:

1. Builds the Python wheel and sdist.
2. Creates a GitHub Release marked pre-release.
3. Publishes to PyPI as a PEP 440 pre-release.

git tag v0.6.0b1
git push origin v0.6.0b1

Switching to pre-release channel:

Users on an existing OAK install can switch to the beta channel from the daemon UI (About dialog) or by editing ~/.oak/update.yaml:

update:
  channel: beta

The daemon automatically checks for and downloads pre-release versions via the self-update system.

---

TestPyPI

Tag vX.Y.Z-testpypi.N on any branch. The workflow:

1. Builds the Python wheel and sdist.
2. Creates a GitHub Release marked pre-release.
3. Publishes to TestPyPI only — nothing goes to real PyPI or Homebrew.

git tag v0.5.0-testpypi.1
git push origin v0.5.0-testpypi.1

User install (for testing only):

pip install oak-ci --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/

---

Cutting a release (checklist)

1. Ensure main is green (make check passes, CI is clean).
2. Update CHANGELOG or release notes if maintained.
3. Create and push the tag (see formats above).
4. Monitor the Release workflow.
5. Verify the GitHub Release was created with the correct prerelease flag.
6. For stable: confirm PyPI shows the new version and brew upgrade oak-ci works.
7. For pre-release: confirm PyPI shows the pre-release version.

Homebrew tap

The tap lives at goondocks-co/homebrew-oak:

Formula	Channel	Class
Formula/oak-ci.rb	Stable	OakCi

The formula is updated automatically by the update-formula.yml workflow, which is triggered by release.yml on stable releases. The HOMEBREW_TAP_TOKEN secret must have workflow scope on the goondocks-co/homebrew-oak repo.