diff --git a/.ciagent/RELEASE_POLICY.md b/.ciagent/RELEASE_POLICY.md new file mode 100644 index 0000000..278d2e4 --- /dev/null +++ b/.ciagent/RELEASE_POLICY.md @@ -0,0 +1,46 @@ +--- +description: CIAgent release and shipping policy — applies to v0.2+ and all subsequent milestones. +--- + +# Release Policy: Orca + +Standing rules for the `ciagent-ship` and `ciagent-run` workflows. These apply to **v0.2+ and every future milestone** of Orca. + +## Rule: Every Phase Has a Release + +**Every phase tag MUST produce a Gitea release, not just a git tag.** + +- A `git tag` alone is a pointer, not a release. Releases carry the built artifact (tarball) and notes. +- For each `vX.Y.Z` phase tag, `ciagent-ship` must invoke `scripts/release.sh vX.Y.Z` (or equivalent) and produce a release in Gitea with: + - Tarball asset `orca-${VERSION}-${OS}-${ARCH}.tar.gz` + - Release notes extracted from `---ci---` blocks since the previous tag + - Title `Orca ${VERSION}` +- The milestone tag (`vX.(Y+1).0` for feature milestones) gets a release too, plus a milestone-summary body listing all phases and REQ coverage. + +## Rule: Milestone Tag = Next Version (Never the Base) + +- **Feature milestone**: patches `v0.5.1`…`v0.5.N` → milestone tag is `v0.(Y+1).0` (NOT `v0.Y.0`). +- **Major milestone**: minors `v0.Z.0` → milestone tag is `v1.0.0`. +- **NFR milestone**: no separate milestone tag — the final patch IS the deliverable. +- Tags must be strictly greater than all existing tags on the same `major.minor` line. + +## Rule: One Tag, One Release, One Push + +For each ship, the sequence is: +1. `git tag -a vX.Y.Z -m "..."` +2. `scripts/release.sh vX.Y.Z` (builds, packages, creates Gitea release with tarball) +3. `git push origin --tags` + +The release step is NOT optional. Skipping the release is a ship failure. + +## Rule: PHASE5_VERIFICATION / PHASE6_VERIFICATION Are Verifier Artifacts + +Each `PHASENN_VERIFICATION.md` in `.ciagent/` is the verifier's report for that phase. These are committed alongside the verification commit and remain in `.ciagent/` as historical evidence for the milestone. They are referenced by the milestone release notes. + +## Rule: PHASE##_VERIFICATION.md Naming + +Phase verification reports are committed as `.ciagent/PHASE##_VERIFICATION.md` (zero-padded, e.g. `PHASE5_VERIFICATION.md`, `PHASE6_VERIFICATION.md`) and are part of the ship record. + +## Why This Matters + +Tags are cheap. Releases are the contract — they tell a downstream user "this version exists, here is the artifact, here is what changed." Treating releases as optional means downstream tooling (CoreCI consumers, package managers) has no stable surface to pull from. Every ship creates a release. No exceptions.