Release process

Document version	Date	Summary
v1	2026-07-19	Define release documentation rollover
v2	2026-07-19	Add release evidence and tag rules
v3	2026-07-20	Add frozen release branch rules

Status: Draft

Related documents: milestones, epics, PBIs, progress, bugs, and known limitations

1. Purpose

This document defines how a release is closed and how active planning documents roll over to the next release.

The goal is to keep active working files small while preserving completed release history. A rollover archives completed release records, resets only the active working sections that are release-local, and carries forward unresolved work.

2. Identifier continuity

Identifiers are permanent.

Do not restart these sequences between releases:

• epic identifiers, such as E08
• PBI identifiers, such as PBI-035
• bug identifiers
• ADR identifiers, such as ADR-006

The archive records where an identifier was completed. The active files continue from the highest identifier already used anywhere in the project.

3. Document classes

3.1 Living documents

Living documents remain in their normal locations and are updated across releases:

Document	Rollover rule
00-spec.md	Keep in place. Update only when product scope or requirements change.
01-milestones.md	Keep in place. Mark the closed release completed and keep future release planning here.
arch/architecture.md	Keep in place. It is the general architecture.
arch/arch-<version>.md	Keep in place. It is already version-specific.
adr/*.md	Keep in place. ADRs are global decision records and are not moved into release archives.
agent-rules.md	Keep in place. Update only when the agent workflow changes.
code-rules.md	Keep in place. Update only when coding rules change.
prompts/*.md	Keep in place. Update only when prompt templates change.
ideas/*.md	Keep in place. Ideas are not release records.
last-development.md	Keep in place. It is the current handoff note, not release history.

3.2 Active planning documents

Active planning documents are snapshotted during rollover and then prepared for the next release:

Document	Archive copy	Active file after rollover
02-epics.md	docs/releases/<version>/epics.md	Keep purpose, rules, and current-release scaffold. Remove completed release epic detail. Continue at the next epic ID.
03-pbis.md	docs/releases/<version>/pbis.md	Keep purpose, structure, shared Definition of Done, and tooling policy. Remove completed release PBI detail. Continue at the next PBI ID.
progress.md	docs/releases/<version>/progress.md	Keep the document header and table schema. Clear the table rows for the next release.
bugs.md	docs/releases/<version>/bugs.md	Keep unresolved or carried-forward bugs. Remove closed release-only bugs from the active file.
known-limitations.md	docs/releases/<version>/known-limitations.md	Keep unresolved or carried-forward limitations. Remove limitations that apply only to the closed release.

Do not delete these active files. Rollover resets or trims their active content only.

4. When to roll over

Perform documentation rollover after all release exit criteria are satisfied and before planning the next release in detail.

The release must have:

• completed included epics and PBIs
• passing required release gates
• recorded known limitations
• recorded deferred bugs
• an updated version architecture document
• an updated milestone status

If a release is abandoned instead of completed, archive it only if the abandoned records are useful historical evidence.

5. Archive location

Each release archive lives under:

docs/releases/<version>/

For example:

docs/releases/v0.1.0/

The release archive should contain:

README.md
evidence.md
epics.md
pbis.md
progress.md
bugs.md
known-limitations.md

Add more files only when they are release records. Do not copy ADRs or version architecture documents into the archive; link to them instead.

6. Archive README template

Use this structure for docs/releases/<version>/README.md:

# Release <version>
 
**Title:** <release title>
 
**Status:** <Completed | Dropped>
 
**Milestone:** <milestone ID or title>
 
**Version architecture:** [Architecture for <version>](../../arch/arch-<version>.md)
 
## Archived records
 
| Record | Source at rollover |
| --- | --- |
| [Evidence](evidence.md) | release gate output and support evidence |
| [Epics](epics.md) | `docs/02-epics.md` |
| [PBIs](pbis.md) | `docs/03-pbis.md` |
| [Progress](progress.md) | `docs/progress.md` |
| [Bugs](bugs.md) | `docs/bugs.md` |
| [Known limitations](known-limitations.md) | `docs/known-limitations.md` |
 
## Identifier continuity
 
Identifiers do not restart after this release. The next active epic, PBI, bug, and ADR identifiers continue from the highest identifiers used before or during this release.
 
## Notes
 
- ADRs remain in `docs/adr/`.
- Version architecture remains in `docs/arch/`.
- Active planning continues in the root planning documents.

7. Release evidence, tags, and frozen branches

A git tag locks the source tree identity for a release. The release archive locks the documentation and verification evidence for that release.

Create docs/releases/<version>/evidence.md before tagging the release. The evidence file should record the verification that was used to accept the release, not the full command output.

Use this structure:

# Release <version> evidence
 
**Release:** `<version>`
 
**Status:** Completed
 
**Source reference:** annotated git tag `<version>`
 
**Verification date:** `<YYYY-MM-DD>`
 
## Required gates
 
| Gate | Command | Result | Notes |
| --- | --- | --- | --- |
| Fast | `./gate.py fast` | <Passed, Failed, or Not run> | <notes> |
| Strict | `./gate.py strict` | <Passed, Failed, or Not run> | <notes> |
| Audit | `./gate.py audit` | <Passed, Failed, or Not run> | <notes> |
 
## Release checks
 
| Check | Evidence | Result | Notes |
| --- | --- | --- | --- |
| GCC build/test | Included in audit gate | <Passed, Failed, or Not run> | <notes> |
| Clang build/test | Included in audit gate | <Passed, Failed, or Not run> | <notes> |
| ASan | Included in strict or audit gate | <Passed, Failed, or Not run> | <notes> |
| UBSan | Included in strict or audit gate | <Passed, Failed, or Not run> | <notes> |
| Cppcheck | Included in fast, strict, or audit gate | <Passed, Failed, or Not run> | <notes> |
| Clang-Tidy | Included in strict or audit gate | <Passed, Failed, or Not run> | <notes> |
| Public header self-containment | Included in strict or audit gate | <Passed, Failed, or Not run> | <notes> |
| Core boundary symbols | Included in strict or audit gate | <Passed, Failed, or Not run> | <notes> |
| Runtime allocation probe | Included in audit gate | <Passed, Failed, or Not run> | <notes> |
| Coverage | Included in audit gate | <Passed, Failed, or Not run> | <notes> |
| Valgrind | Included in audit gate | <Passed, Failed, or Not run> | <notes> |
| Support matrix | Included in audit gate or checked manually | <Passed, Failed, or Not run> | <notes> |
 
## Coverage
 
| Target | Line coverage | Branch coverage | Notes |
| --- | ---: | ---: | --- |
| Pet Core | <value> | <value> | <source report> |
 
## Support status
 
| Environment | Status | Notes |
| --- | --- | --- |
| Linux GCC | <Verified, Designed, or Unsupported> | <notes> |
| Linux Clang | <Verified, Designed, or Unsupported> | <notes> |
| Windows MSVC | <Verified, Designed, or Unsupported> | <notes> |
| Embedded | <Verified, Designed, or Unsupported> | <notes> |
 
## Notes
 
- Evidence is valid for annotated git tag `<version>`.
- Future fixes require a new commit and a patch release tag, such as `<next-patch-version>`.

After evidence.md is committed, run the required final release gate again against the exact commit that will be tagged. Then create an annotated tag:

git tag -a <version> -m "release <version>"

Create a frozen release branch at the same commit:

git branch release-<version> <version>

For example, release v0.1.0 has tag v0.1.0 and branch release-v0.1.0. Do not create a branch named exactly like the tag.

The tag remains the release lock. The frozen branch is a protected reference and patch-release starting point. Create both from the release maintainer’s local clone after the final gate passes, then push both to the Git host.

In the Git host, protect release refs before normal development continues:

• protect branch pattern release-v*
• protect tag pattern v*
• disable force pushes
• allow direct updates only for maintainers, or require a merge request when the host supports it

Do not move a frozen release branch unless a maintainer explicitly approves correcting the release reference. Future fixes require a new commit on the frozen branch and a patch release tag, such as v0.1.1.

8. Active file rollover rules

8.1 02-epics.md

After archiving, keep:

• document title
• document version table
• status
• current release field
• related document links
• purpose
• epic completion rules
• a new release epic map for the next release

Remove completed release epic bodies from the active file. Replace them with a short archive pointer.

The active file must state the next epic identifier explicitly:

Epic identifiers continue from `E08`.
Completed `v0.1.0` epics are archived in [release v0.1.0](releases/v0.1.0/epics.md).

8.2 03-pbis.md

After archiving, keep:

• document title
• document version table
• purpose
• PBI structure
• shared Definition of Done
• quality tooling policy
• any cross-release backlog rules

Remove completed release PBI bodies from the active file. Replace them with a short archive pointer.

The active file must state the next PBI identifier explicitly:

PBI identifiers continue after `PBI-034`.
Completed `v0.1.0` PBIs are archived in [release v0.1.0](releases/v0.1.0/pbis.md).

8.3 progress.md

After archiving, keep:

• document title
• document version table, if present
• purpose or usage notes, if present
• table header

Clear completed release rows from the active table. Add a short archive pointer above the table.

Do not delete the file and do not add a normal progress row for the rollover task itself unless the rollover is part of a PBI.

The active table should be empty immediately after rollover:

Completed `v0.1.0` progress is archived in [release v0.1.0](releases/v0.1.0/progress.md).
 
| Date | Scope | Change | Verification | Notes |
| --- | --- | --- | --- | --- |

8.4 bugs.md

After archiving, keep only:

• unresolved bugs
• bugs explicitly deferred to a future release
• bug process notes

Closed bugs that only document the completed release should remain only in the archive.

For every carried-forward bug, preserve its original identifier and add or keep the target release if known.

8.5 known-limitations.md

After archiving, keep only:

• limitations that are still true after the closed release
• limitations intentionally deferred to a future release
• limitation process notes

Resolved limitations that only document the completed release should remain only in the archive.

For every carried-forward limitation, preserve the original wording unless the scope changed. If the scope changed, edit the active file and leave the archived copy unchanged.

9. Archive immutability

Archived release files are historical records. Do not edit them during normal future planning.

Allowed archive edits are limited to:

• fixing a broken relative link
• correcting an accidental archival omission
• correcting a typo that changes meaning
• adding a note that clearly marks itself as a later correction

Do not rewrite archived acceptance criteria, completion state, or release evidence to match later project decisions.

10. Rollover checklist

Use this checklist when closing a release:

- [ ] Confirm release exit criteria are complete.
- [ ] Confirm required gates have passed.
- [ ] Create `docs/releases/<version>/`.
- [ ] Create `docs/releases/<version>/README.md`.
- [ ] Create `docs/releases/<version>/evidence.md`.
- [ ] Copy `02-epics.md` to `docs/releases/<version>/epics.md`.
- [ ] Copy `03-pbis.md` to `docs/releases/<version>/pbis.md`.
- [ ] Copy `progress.md` to `docs/releases/<version>/progress.md`.
- [ ] Copy `bugs.md` to `docs/releases/<version>/bugs.md`.
- [ ] Copy `known-limitations.md` to `docs/releases/<version>/known-limitations.md`.
- [ ] Update `01-milestones.md` release status.
- [ ] Prepare `02-epics.md` for the next release.
- [ ] Prepare `03-pbis.md` for the next release.
- [ ] Clear completed release rows from `progress.md`.
- [ ] Carry unresolved bugs forward in `bugs.md`.
- [ ] Carry unresolved limitations forward in `known-limitations.md`.
- [ ] Verify active files link to the release archive.
- [ ] Verify release archive links back to living architecture and ADR records where needed.
- [ ] Commit the archive and evidence.
- [ ] Run the final required release gate on the exact commit to tag.
- [ ] Create an annotated git tag for the release.
- [ ] Create `release-<version>` from the same commit as the tag.
- [ ] Push the tag and frozen branch to the Git host.
- [ ] Protect `v*` tags and `release-v*` branches in the Git host.
- [ ] Run `git diff --check`.

11. Special task rule

A documentation rollover task is release maintenance. It does not update progress.md or last-development.md unless a PBI explicitly requires that update.