probo/contrib/claude/release/README.md

Release

The repository ships nine independently-versioned tracks. Each has its own version source, its own CHANGELOG.md, its own tag pattern, and its own release workflow. Cutting a release means: bump the version, write a changelog entry, commit, tag, push.

Track	Tag pattern	Entrypoint
CLI (prb)	prb/v*	prb.md
Server (probod group)	probod/v*	probod.md
probod-bootstrap	probod-bootstrap/v*	probod-bootstrap.md
proboctl	proboctl/v*	proboctl.md
probo-agent	probo-agent/v*	probo-agent.md
@probo/n8n-nodes-probo	@probo/n8n-nodes-probo/v*	n8n-nodes-probo.md
@probo/cookie-banner	@probo/cookie-banner/v*	cookie-banner.md
@probo/skills	@probo/skills/v*	skills.md
Helm chart (probo)	helm/v*	helm.md

When the user asks for a release without specifying a track, follow Step 1 below to detect which tracks have user-facing changes since their last tag, then ask the user which of those tracks to release. Only release tracks that actually have user-facing changes. Never release a track that has no commits since its last tag.

When the user asks for a release for a specific track (e.g. "release the CLI", "release probod"), open the corresponding entrypoint above and follow it.

Versions are SemVer in the 0.x series. Never bump MAJOR. Bug fixes only -> bump PATCH; new features or non-breaking changes -> bump MINOR.

1. Decide which tracks to release

Before any release, identify which tracks have user-facing commits since their last tag. A track with zero commits, or only non-user-facing commits (style, CI, internal refactors, doc-only, release commits) must not be released.

Run this from a clean main:

git checkout main && git pull origin main

Then for each track, list commits since its last tag, scoped to that track's paths:

# prb
git log $(git describe --tags --abbrev=0 --match='prb/v*')..HEAD --oneline \
  -- cmd/prb pkg/cli pkg/cmd

# probod (server group: probod + console + trust + ui)
git log $(git describe --tags --abbrev=0 --match='probod/v*')..HEAD --oneline \
  -- cmd/probod apps/console apps/trust packages/ui pkg

# probod-bootstrap
git log $(git describe --tags --abbrev=0 --match='probod-bootstrap/v*')..HEAD --oneline \
  -- cmd/probod-bootstrap

# proboctl
git log $(git describe --tags --abbrev=0 --match='proboctl/v*')..HEAD --oneline \
  -- cmd/proboctl pkg/proboctl

# probo-agent
git log $(git describe --tags --abbrev=0 --match='probo-agent/v*')..HEAD --oneline \
  -- cmd/probo-agent pkg/deviceagent

# @probo/n8n-nodes-probo
git log $(git describe --tags --abbrev=0 --match='@probo/n8n-nodes-probo/v*')..HEAD --oneline \
  -- packages/n8n-node

# @probo/cookie-banner
git log $(git describe --tags --abbrev=0 --match='@probo/cookie-banner/v*')..HEAD --oneline \
  -- packages/cookie-banner

# @probo/skills
git log $(git describe --tags --abbrev=0 --match='@probo/skills/v*')..HEAD --oneline \
  -- packages/skills

# helm chart
git log $(git describe --tags --abbrev=0 --match='helm/v*')..HEAD --oneline \
  -- contrib/helm

If a track returns no commits, skip it. If all commits for a track are non-user-facing, skip it (and tell the user). For each remaining track, proceed with its entrypoint.

2. Writing a changelog entry

Categorize entries under Keep-a-Changelog sections in the relevant track's CHANGELOG.md:

Section	Use for
### Added	New features, new commands, new endpoints
### Changed	Behavioral changes, refactors visible to users
### Fixed	Bug fixes
### Removed	Removed features or deprecated code

Skip non-user-facing commits (style/formatting, CI-only, internal refactors, doc-only, release commits).

Only list fixes for pre-existing bugs. If a "fix" commit repairs something introduced earlier in the same release cycle, do NOT list it as a separate fix.

Summarize related commits into a single line when appropriate.

Format: ## [X.Y.Z] - YYYY-MM-DD (today's date). Always keep an ## Unreleased heading above the latest version.

3. Common steps (every track)

Open the per-track entrypoint and run its Detect commits command. If the track has no user-facing commits, stop. Otherwise:

1. Decide the version bump (PATCH for fixes, MINOR for features).
2. Bump the version using the track's Version bump method.
3. If the track lists a Build command, run it now to catch compile errors before tagging.
4. Write the changelog entry in the track's Changelog file following the rules in section 2.
5. Show the user the proposed changelog diff and the new version. Wait for confirmation.
6. Stage only the files listed in the track's Files to stage. Commit subject: Release <pkg>/v<version>. No body.
7. Annotated tag: git tag -a <pkg>/v<version> -m "<pkg>/v<version>".
8. Push the commit: git push origin main.
9. Push the tag separately: git push origin <pkg>/v<version>.

Each tag must be pushed in its own git push command so the corresponding GitHub Actions workflow fires reliably. Pushing multiple tags at once (e.g. --follow-tags) can silently skip workflow triggers.

When releasing multiple tracks in one session, push each track's tag immediately after creating it, before moving on to the next track.

Checklist (every track)

1. Pulled latest main
2. Track has user-facing commits since its last tag
3. Version bumped per track's Version bump method
4. (npm tracks) Build command succeeded
5. Changelog entry written, categorized, summarized
6. User confirmed changelog and version
7. Commit: Release <pkg>/v<version>
8. Annotated tag <pkg>/v<version>
9. Pushed commit to main
10. Pushed tag independently