agentic-dev/docs/decisions/adr-021-versioning-and-changelog.md

# ADR-021 — Hybrid versioning + automated changelog via release-please

**Status:** Accepted
**Date:** 2026-05-13
**Builds on:** Conventional Commits convention (CLAUDE.md Key Conventions), ADR-019 (sandcastle agent orchestration)

## Context

Until this ADR the template had no versioning + no changelog. Every package shipped at `0.0.0`; there was no tag history, no "what changed since I forked this" answer, and no formal cadence for surfacing meaningful state changes.

Two pressures motivated wiring this up now:

1. **Conventional Commits had just been mandated** (visible across CLAUDE.md, AGENTS.md, session-start, and prompt-context hooks). Conventional commits are the substrate that automated versioning tools consume — leaving them unused would waste a free signal.
2. **The template is a fork target.** Downstream consumers need a version they can pin against ("I forked at v0.3.0, what's changed?") and a changelog they can diff.

The available tools fall in three families:

- **Changesets** (`@changesets/cli`) — contributors run `pnpm changeset` per PR; explicit semver intent. Higher friction; not needed when conventional commits are already mandated.
- **semantic-release** — fully automated from conventional commits; publishes on merge. Less control; monorepo support requires extra plumbing.
- **release-please** (Google) — parses conventional commits, opens a rolling release PR with bumps + CHANGELOG entries; merging the PR cuts tags + GitHub releases.

`release-please` is the natural fit: conventional commits are already enforced, and the "release PR" model gives a human approval gate without requiring per-commit changeset files.

The remaining design choice is **versioning scope**:

- **Single root version** — one CHANGELOG.md at the root; the whole template moves together. Simplest.
- **Per-package versions** — every `@repo/*` package versions independently; one CHANGELOG.md per package. Useful for published packages; we publish nothing today.
- **Hybrid** — root template version (for cross-cutting changes: docs, scripts, ci, generators, core packages) + per-feature versions (for `packages/<feature>/**` changes). One root CHANGELOG.md + one per feature. Decision boundary follows commit-path scoping.

## Decision

**1. Adopt `release-please` (Google) as the versioning + changelog substrate.** Configuration in `release-please-config.json` and `.release-please-manifest.json` at the repo root. The GitHub Action lives at `.github/workflows/release-please.yml` and runs on every push to `main`.

**2. Hybrid versioning scope.** Six tracked packages:

| Path                       | Package name            | Component (tag prefix) | Initial version |
| -------------------------- | ----------------------- | ---------------------- | --------------- |
| `.`                        | `template-vertical`     | `template`             | `0.1.0`         |
| `packages/auth`            | `@repo/auth`            | `auth`                 | `0.1.0`         |
| `packages/blog`            | `@repo/blog`            | `blog`                 | `0.1.0`         |
| `packages/media`           | `@repo/media`           | `media`                | `0.1.0`         |
| `packages/marketing-pages` | `@repo/marketing-pages` | `marketing-pages`      | `0.1.0`         |
| `packages/navigation`      | `@repo/navigation`      | `navigation`           | `0.1.0`         |

Each gets its own `CHANGELOG.md`. Tags use the per-package component prefix to avoid collisions: `template-v0.2.0`, `auth-v0.1.1`, etc.

Core packages (`core-shared`, `core-cms`, `core-api`, `core-eslint`, `core-typescript`, `core-testing`) and optional cores (`core-events`, `core-realtime`, etc., when scaffolded) are **NOT** independently versioned. Cross-cutting changes to those land in the root template version. Rationale: those packages cascade — bumping `core-shared` would functionally invalidate every feature anyway; surfacing them as separate versions creates noise without information. If a future consumer publishes individual core packages downstream, they can add per-package tracking then.

Apps (`web-next`, `web-tanstack`, `cms`, `storybook`) stay at `0.0.0`. They're not consumable artifacts.

**3. Pre-1.0 bump policy.** While each tracked package is `<1.0.0`:

- `feat:` commits bump **patch** (not minor), per `bump-patch-for-minor-pre-major: true`
- `fix:` commits bump patch
- `feat!:` (or any `BREAKING CHANGE:` footer) bumps **minor** (not major)
- `chore`, `ci`, `build`, `style`, `test` commits don't bump

Rationale: the conservative pre-1.0 default means surface area can change without exhausting the version space. When a package crosses `1.0.0`, standard semver kicks in.

**4. Conventional-commit type → changelog section mapping.** From `release-please-config.json`:

| Type                                    | Section       | Hidden |
| --------------------------------------- | ------------- | ------ |
| `feat`                                  | Features      | no     |
| `fix`                                   | Bug Fixes     | no     |
| `perf`                                  | Performance   | no     |
| `refactor`                              | Refactoring   | no     |
| `docs`                                  | Documentation | no     |
| `revert`                                | Reverts       | no     |
| `test`, `chore`, `ci`, `build`, `style` | (omitted)     | yes    |

Hidden sections still drive version bumps where applicable (none do, by current policy) but don't clutter the changelog.

**5. Bump targeting is by commit-path, not commit-scope.** release-please decides which package(s) to bump based on the _files changed_ in a commit, NOT the conventional-commit `scope`. A commit changing `packages/auth/**` bumps `@repo/auth`; a commit changing `docs/**` or `scripts/**` or `CLAUDE.md` bumps the root template; a commit changing both bumps both. The conventional-commit `scope` field is for human readability in the changelog — it does not drive routing.

**6. Release PR is a rolling document.** Every push to main re-evaluates the open release PR. Merging it cuts tags + creates GitHub releases for each affected package. No manual edits to the PR — the changelog content is reproducible from the commit history.

**7. CHANGELOG files are committed and edited only by release-please.** Manual edits are discouraged because they will be overwritten the next time release-please assembles the rolling PR. Initial baseline content for each `0.1.0` entry is the only exception.

## Alternatives considered

- **Changesets (`@changesets/cli`)** — rejected primarily because Conventional Commits already capture the necessary intent. Per-PR changeset files would duplicate information. Could revisit if release-please ever fails to handle a release-shape edge case (e.g. needing a manual bump that's larger than commits imply).
- **semantic-release** — rejected for monorepo friction. Per-package support requires `semantic-release-monorepo` or `multi-semantic-release`; release-please handles this natively.
- **Single root version** — rejected because cross-cutting commits ARE a different kind of change from feature commits. A `fix(media): off-by-one in upload` shouldn't churn the root template version; a `refactor(coverage): unify L0 thresholds` shouldn't churn `@repo/auth`'s version. Separating gives consumers a finer-grained "what changed for me" signal.
- **Per-package for every workspace member (apps, core, tooling)** — rejected. Core packages cascade; bumping `core-shared` is effectively a template-wide change. Apps aren't consumable. Tooling churn is mostly mechanical. Adding versions for these adds bookkeeping without information value.
- **Tag prefix `template-vertical-v...` vs `template-v...`** — chose `template-v` for tag economy (shorter; consistent length with `auth-v`, `blog-v`, etc.). The package name `template-vertical` is still authoritative in `package.json`.
- **Auto-merge the release PR** — rejected. Human approval is the gate that catches the rare case where a commit's content doesn't match its conventional type (e.g. a `chore:` commit that actually shipped a feature).

## Consequences

**Positive:**

- Every merge to main produces a tracked, dated record of what changed for downstream consumers.
- Conventional commits become load-bearing: their type + body shape the changelog directly.
- The "what version did I fork at" question has a real answer per tracked package.
- Tagged releases enable `git diff vX.Y.Z..HEAD -- <path>` for narrow "what changed in feature X since I last looked" questions.
- Release cadence is implicit (merge the PR when ready); no separate release planning required.

**Negative:**

- Six packages × independent versions means six CHANGELOG.md files to navigate. Mitigated by the `## Cross-references` section in each pointing at the relevant ADRs + this one.
- release-please-action is GitHub-Actions-coupled. A migration to a different CI provider would need a different runner (the release-please core CLI runs anywhere, but the orchestration around the rolling PR is Action-specific).
- The first release PR after the initial baseline could be large (covers everything merged after `0.1.0`). This is one-time; subsequent PRs are scoped to the work between releases.
- Apps stuck at `0.0.0` is mildly confusing if a contributor expects every package to be versioned. Mitigated by documentation here + in `docs/guides/releasing.md`.

## Related

- ADR-019 — sandcastle agent orchestration (the dispatch loop that ships these commits)
- ADR-020 — coverage architecture (one of the systems shipped at the 0.1.0 baseline)
- CLAUDE.md Key Conventions — Conventional Commits requirement (the substrate this ADR consumes)
- `docs/guides/releasing.md` — day-to-day cookbook