Release Process

Release Process: Tagging, Publishing, and Shipping Stable Compitum Versions

Quick-Scan Infobox

Aspect	Details
Target User	Developers maintaining forks, educators forking for class versions; Git basics assumed.
Core Goal	Streamline from CI green to GitHub Release—ensure auditable bumps, tags, and artifacts for reproducible loops.
Time to First Tag	10 mins: Lint CHANGELOG → Tag → Push → Draft release.
Key Analogy	Like quest completion in a skill tree: Verify prereqs (CI), log the lore (CHANGELOG), pin the milestone (tag), share the loot (artifacts).
Prereqs	Green main, updated pyproject.toml; optional PyPI creds.

Core Principles Layer (Technical Backbone)

Compitum's releases follow semantic versioning (SemVer: MAJOR.MINOR.PATCH) for bounded evolution: Major for API breaks (e.g., metric rank changes), minor for features (e.g., new signals), patch for fixes (e.g., NaN clips). Workflow: CI invariants (pytest, lint) gate merges; post-merge, bump via bump2version or manual in pyproject.toml (e.g., version = "1.0.1"), annotate CHANGELOG with signal-like entries ("Added shadow variance: +0.2 stability"). Tag with -a for signed GPG (optional: git tag -a v1.0.1 -m "v1.0.1: Boundary entropy fix"), push refs to trigger GitHub Actions (docs build, PyPI if flagged). Releases auto-generate from tags; manual drafts link artifacts (traces, reports) under data/eval_results/. PyPI optional: twine upload dist/* post-build—ensures pip-installable for classroom venvs.

• SemVer Formal: vMAJOR.MINOR.PATCH; pre-releases as v1.0.1-rc1. CHANGELOG append-only: Sections per version, bullet impacts (e.g., "Constraints: Shadow approx O(ε) via finite diff").
• CI Gate: GitHub Actions yaml: pytest -m all --cov=src; fails on <95% cov or violations.
• In Practice: Repo RELEASE.md details hooks; CHANGELOG.md as audit trail—e.g., "v1.0.0: Initial quadratic router."

Why this flow? Mirrors bounded observers: CI as feas check, tag as cert, release as emergent share—stable paths without overload.

Code Dive: Automated Bump and Tag (Collapsible for Tinkerers)

# Bump Script: From RELEASE.md (Extendable)
# Requires bump2version: pip install bump2version

bump2version patch  # Or minor/major; updates pyproject.toml
git add pyproject.toml CHANGELOG.md
git commit -m "Bump v1.0.1: [brief signal, e.g., drift EMA tune]"
git tag -a v1.0.1 -m "Compitum v1.0.1: Stability enhancements"
git push origin main
git push origin v1.0.1  # Triggers Actions

# PyPI: If flagged
python -m build
twine upload dist/* --skip-existing

Pro Tip: GPG sign: git config --global user.signingkey ID; verify git tag -v v1.0.1.

Approachable Layer (Relatable Hooks for Educators)

Releasing's the "wrap-up and share" of your lesson series: CI green as "all kids checked in," CHANGELOG the reflection log ("What clicked? Drifts down 10%!"), tag the milestone badge, release the take-home kit (docs, traces). No heroics—just methodical handoffs, like passing the quadratic baton to next period. For teachers, it's versioning your curriculum: Fork for class tweaks, tag "v1.2-edu" with coherence boosts—empowers collab without version hell.

• Classroom Tie-In: Treat CHANGELOG as post-unit eval—bullets as "emergent wins" (e.g., "Boundaries: +15% flag accuracy"); share releases as "module packs" for sub teams.
• Analogy Echo: Push as the bell ring: Artifacts out the door, ready for next loop's queries.
• Common Hurdle: CHANGELOG bloat? Template bullets: "Fixed [signal]; Added [guard]."

Quick-Reference Toolkit (Release Steps)

Step	Action	Tools/Checks	Output	Gotcha
1. CI Green	Merge to main; run workflows.	GitHub Actions: pytest/lint/cov.	Green badge.	Red? Fix invariants first.
2. Bump & Log	Edit CHANGELOG.md; bump pyproject.toml.	bump2version or manual.	v1.0.1 entry.	SemVer: Minor for feats, patch for bugs.
3. Tag & Push	git tag -a vX.Y.Z -m "..." && git push origin vX.Y.Z.	GPG optional.	Remote tag.	Unsigned? Fine for internal; sign for prod.
4. GitHub Release	Draft new release from tag.	Links: Docs, reports (e.g., eval JSONs).	Tagged page w/ assets.	Attach zips? For traces; markdown for notes.
Opt: PyPI	python -m build && twine upload.	Per RELEASE.md.	pip install compitum==1.0.1.	Skippable; test twine check.

Troubleshooting Table (Collapsible: Release Hiccups)

Issue	Symptom	Fix	Analogy
CI Fail	Tests red post-merge.	Revert or hotfix; pytest -v.	Stormy launch—shelter first.
Tag Conflict	Push rejected.	git tag -d v1.0.1; git push --delete origin v1.0.1.	Double-booked flight—reschedule.
PyPI 403	Upload auth fail.	twine upload --username __token__ --password pypi-....	Wrong ticket—validate creds.
Changelog Miss	No entry for bump.	Append before commit: "v1.0.1: [3-5 bullets]".	Forgetting notes—jot the highlights.

Next Steps: Your Loop

• Sim a Release: Bump a dev branch, tag locally—push if green?
• Audit Changelog: Grep for "shadow"—coverage gaps?
• Automate: PR a GitHub Action for bump-on-merge.

See also: Repo RELEASE.md / CHANGELOG.md; Roadmap for version plans; Verification for CI ties; Cookbook for bash recipes.