From 8bd5454ad7a760ab5051bd4901e2a3a8825c3591 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89mile=20R=C3=A9?= Date: Thu, 7 May 2026 16:49:58 +0400 Subject: [PATCH] Update release guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Émile Ré --- contrib/claude/release/README.md | 53 ++++++++------ contrib/claude/release/cookie-banner.md | 84 +++++++--------------- contrib/claude/release/n8n-nodes-probo.md | 63 +++++----------- contrib/claude/release/prb.md | 44 ++++-------- contrib/claude/release/probod-bootstrap.md | 48 +++++-------- contrib/claude/release/probod.md | 51 ++++++------- 6 files changed, 124 insertions(+), 219 deletions(-) diff --git a/contrib/claude/release/README.md b/contrib/claude/release/README.md index bada19287..e5876b187 100644 --- a/contrib/claude/release/README.md +++ b/contrib/claude/release/README.md @@ -96,32 +96,39 @@ Format: `## [X.Y.Z] - YYYY-MM-DD` (today's date). Always keep an ## 3. Common steps (every track) -After choosing the track and reviewing its commits: +Open the per-track entrypoint and run its **Detect commits** command. +If the track has no user-facing commits, stop. Otherwise: -1. Bump the version in the track's source of truth (see the per-track - entrypoint). -2. Write the changelog entry in the track's `CHANGELOG.md`. -3. For npm tracks, run the workspace `build` script after the version - bump (see the per-track entrypoint for why). -4. Show the user the proposed `CHANGELOG.md` diff and the new version. - Wait for confirmation. -5. Commit only the files modified by the version bump and changelog - edit. Subject: `Release /v`. No body. -6. Annotated tag: `git tag -a /v -m "/v"`. -7. Push: `git push origin main --follow-tags`. +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](#2-writing-a-changelog-entry). +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 /v`. No body. +7. Annotated tag: `git tag -a /v -m "/v"`. +8. Push the commit: `git push origin main`. +9. Push the tag **separately**: `git push origin /v`. -CI handles the rest: binary builds, npm publish, Docker image, Homebrew -formula, SBOMs, attestations, GitHub Release. +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. [ ] Confirmed the track has user-facing commits since its last tag -3. [ ] Reviewed track-specific commits -4. [ ] Track CHANGELOG entry written, categorized, summarized -5. [ ] Version bumped in the track's source of truth -6. [ ] (npm tracks) Workspace `build` script run successfully after bump -7. [ ] User confirmed changelog and version -8. [ ] Commit message is `Release /v` -9. [ ] Annotated tag `/v` on the release commit -10. [ ] Pushed commit and tag +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 /v` +8. [ ] Annotated tag `/v` +9. [ ] Pushed commit to `main` +10. [ ] Pushed tag independently diff --git a/contrib/claude/release/cookie-banner.md b/contrib/claude/release/cookie-banner.md index a3f1f7daf..1559afd11 100644 --- a/contrib/claude/release/cookie-banner.md +++ b/contrib/claude/release/cookie-banner.md @@ -1,73 +1,37 @@ # Release `@probo/cookie-banner` -Entrypoint for releasing the cookie banner SDK. Read -[README.md](./README.md) first for overall flow, changelog rules, and the -non-empty-track guarantee. +After confirming commits below, follow the +[common steps](./README.md#3-common-steps-every-track). ## Track facts - **Tag pattern**: `@probo/cookie-banner/v*` - **Version source**: `packages/cookie-banner/package.json` +- **Version bump**: `npm --workspace @probo/cookie-banner version --no-git-tag-version` +- **Build**: `npm --workspace @probo/cookie-banner run build` - **Changelog**: `packages/cookie-banner/CHANGELOG.md` +- **Files to stage**: `packages/cookie-banner/package.json`, + `packages/cookie-banner/CHANGELOG.md`, `package-lock.json` - **Workflow**: `.github/workflows/release-npm-cookie-banner.yaml` -- **Path filter** (for log/scoping): `packages/cookie-banner` +- **Path filter**: `packages/cookie-banner` -## Important: build script bakes the version +## Detect commits + +```shell +git log $(git describe --tags --abbrev=0 --match='@probo/cookie-banner/v*')..HEAD --oneline \ + -- packages/cookie-banner +``` + +If empty or non-user-facing only, do not release this track. + +## Notes `packages/cookie-banner/build.mjs` reads `version` from `package.json` -and exposes it to the bundle as the `__SDK_VERSION__` define. The SDK -uses this value at runtime (e.g. when calling the Probo REST API), so -the build **must** run after the version bump to make sure the new -version is what gets published. The release CI workflow does run the -build, but we still run it locally as part of the release commit so: +and exposes it as the `__SDK_VERSION__` define. The SDK uses this at +runtime, so the build **must** run after the version bump. The release CI +also runs the build, but running it locally catches compile errors before +tagging and ensures tracked side-effects (`package-lock.json`) are part +of the release commit. -- compile errors are caught before tagging, -- any tracked side-effects (`package-lock.json`, etc.) are part of the - same `Release @probo/cookie-banner/v` commit. - -## Steps - -1. From a clean `main`, list commits since the last - `@probo/cookie-banner` tag: - - ```shell - git log $(git describe --tags --abbrev=0 --match='@probo/cookie-banner/v*')..HEAD --oneline \ - -- packages/cookie-banner - ``` - - If the list is empty (or contains only non-user-facing commits), do - not release this track. - -2. Decide the version bump (PATCH for fixes, MINOR for features). -3. Bump the version using npm so `package.json` and `package-lock.json` - stay consistent: - - ```shell - npm --workspace @probo/cookie-banner version --no-git-tag-version - ``` - -4. Run the workspace build so `__SDK_VERSION__` is rebuilt from the new - `package.json` and any compile error surfaces before we tag: - - ```shell - npm --workspace @probo/cookie-banner run build - ``` - - `dist/` is gitignored, so this step does not produce checked-in build - artifacts — but it must succeed for the release to be valid. - -5. Write the new entry in `packages/cookie-banner/CHANGELOG.md` following - the rules in [README.md](./README.md#2-writing-a-changelog-entry). -6. Show the user the changelog diff and the new version. Wait for - confirmation. -7. Stage the files modified by the version bump and changelog edit - (typically `packages/cookie-banner/package.json`, - `packages/cookie-banner/CHANGELOG.md`, and `package-lock.json`). - Commit subject: `Release @probo/cookie-banner/v`. No body. -8. Annotated tag: - `git tag -a @probo/cookie-banner/v -m "@probo/cookie-banner/v"`. -9. Push: `git push origin main --follow-tags`. - -CI workflow `release-npm-cookie-banner.yaml` verifies the tag matches -`package.json`, runs the build again, publishes to npm with provenance + -SBOM, and creates a GitHub Release. +CI verifies the tag matches `package.json`, runs the build, publishes to +npm with provenance + SBOM, and creates a GitHub Release. diff --git a/contrib/claude/release/n8n-nodes-probo.md b/contrib/claude/release/n8n-nodes-probo.md index 7cdee5842..75364f99c 100644 --- a/contrib/claude/release/n8n-nodes-probo.md +++ b/contrib/claude/release/n8n-nodes-probo.md @@ -1,58 +1,31 @@ # Release `@probo/n8n-nodes-probo` -Entrypoint for releasing the n8n nodes package. Read -[README.md](./README.md) first for overall flow, changelog rules, and the -non-empty-track guarantee. +After confirming commits below, follow the +[common steps](./README.md#3-common-steps-every-track). ## Track facts -- **Tag pattern**: `@probo/n8n-nodes-probo/v*` (the `@` and `/` are valid - in Git tag refs) +- **Tag pattern**: `@probo/n8n-nodes-probo/v*` (the `@` and `/` are + valid in Git tag refs) - **Version source**: `packages/n8n-node/package.json` +- **Version bump**: `npm --workspace @probo/n8n-nodes-probo version --no-git-tag-version` +- **Build**: `npm --workspace @probo/n8n-nodes-probo run build` - **Changelog**: `packages/n8n-node/CHANGELOG.md` +- **Files to stage**: `packages/n8n-node/package.json`, + `packages/n8n-node/CHANGELOG.md`, `package-lock.json` - **Workflow**: `.github/workflows/release-npm-n8n-node.yaml` -- **Path filter** (for log/scoping): `packages/n8n-node` +- **Path filter**: `packages/n8n-node` -## Steps +## Detect commits -1. From a clean `main`, list commits since the last - `@probo/n8n-nodes-probo` tag: +```shell +git log $(git describe --tags --abbrev=0 --match='@probo/n8n-nodes-probo/v*')..HEAD --oneline \ + -- packages/n8n-node +``` - ```shell - git log $(git describe --tags --abbrev=0 --match='@probo/n8n-nodes-probo/v*')..HEAD --oneline \ - -- packages/n8n-node - ``` +If empty or non-user-facing only, do not release this track. - If the list is empty (or contains only non-user-facing commits), do - not release this track. +## Notes -2. Decide the version bump (PATCH for fixes, MINOR for features). -3. Bump the version using npm so `package.json` and `package-lock.json` - stay consistent: - - ```shell - npm --workspace @probo/n8n-nodes-probo version --no-git-tag-version - ``` - -4. Run the workspace build to confirm it succeeds with the new version - (and to surface any compile errors before we tag): - - ```shell - npm --workspace @probo/n8n-nodes-probo run build - ``` - -5. Write the new entry in `packages/n8n-node/CHANGELOG.md` following the - rules in [README.md](./README.md#2-writing-a-changelog-entry). -6. Show the user the changelog diff and the new version. Wait for - confirmation. -7. Stage the files modified by the version bump and changelog edit - (typically `packages/n8n-node/package.json`, - `packages/n8n-node/CHANGELOG.md`, and `package-lock.json`). Commit - subject: `Release @probo/n8n-nodes-probo/v`. No body. -8. Annotated tag: - `git tag -a @probo/n8n-nodes-probo/v -m "@probo/n8n-nodes-probo/v"`. -9. Push: `git push origin main --follow-tags`. - -CI workflow `release-npm-n8n-node.yaml` verifies the tag matches -`package.json`, publishes to npm with provenance + SBOM, and creates a -GitHub Release. +CI verifies the tag matches `package.json`, publishes to npm with +provenance + SBOM, and creates a GitHub Release. diff --git a/contrib/claude/release/prb.md b/contrib/claude/release/prb.md index dd4a755a0..ea63bebcf 100644 --- a/contrib/claude/release/prb.md +++ b/contrib/claude/release/prb.md @@ -1,42 +1,28 @@ # Release `prb` (CLI) -Entrypoint for releasing the `prb` CLI. Read [README.md](./README.md) -first for overall flow, changelog rules, and the -non-empty-track guarantee. +After confirming commits below, follow the +[common steps](./README.md#3-common-steps-every-track). ## Track facts - **Tag pattern**: `prb/v*` -- **Version source**: `cmd/prb/VERSION` (contains only `X.Y.Z`) +- **Version source**: `cmd/prb/VERSION` (single `X.Y.Z` line) +- **Version bump**: Edit `cmd/prb/VERSION` directly - **Changelog**: `cmd/prb/CHANGELOG.md` +- **Files to stage**: `cmd/prb/VERSION`, `cmd/prb/CHANGELOG.md` - **Workflow**: `.github/workflows/release-prb.yaml` -- **Path filter** (for log/scoping): `cmd/prb pkg/cli pkg/cmd` +- **Path filter**: `cmd/prb pkg/cli pkg/cmd` -## Steps +## Detect commits -1. From a clean `main`, list commits since the last `prb` tag: +```shell +git log $(git describe --tags --abbrev=0 --match='prb/v*')..HEAD --oneline \ + -- cmd/prb pkg/cli pkg/cmd +``` - ```shell - git log $(git describe --tags --abbrev=0 --match='prb/v*')..HEAD --oneline \ - -- cmd/prb pkg/cli pkg/cmd - ``` +If empty or non-user-facing only, do not release this track. - If the list is empty (or contains only non-user-facing commits), do - not release this track. +## Notes -2. Decide the version bump (PATCH for fixes, MINOR for features). -3. Bump the version in `cmd/prb/VERSION` (the file contains a single - `X.Y.Z` line — no trailing newline conventions beyond what is already - there). -4. Write the new entry in `cmd/prb/CHANGELOG.md` following the rules in - [README.md](./README.md#2-writing-a-changelog-entry). -5. Show the user the changelog diff and the new version. Wait for - confirmation. -6. Stage only `cmd/prb/VERSION` and `cmd/prb/CHANGELOG.md`. Commit - subject: `Release prb/v`. No body. -7. Annotated tag: `git tag -a prb/v -m "prb/v"`. -8. Push: `git push origin main --follow-tags`. - -CI workflow `release-prb.yaml` builds binaries for 9 OS/arch targets, -publishes a GitHub Release, and updates the Homebrew formula at -`getprobo/homebrew-tap`. +CI builds binaries for 9 OS/arch targets, publishes a GitHub Release, +and updates the Homebrew formula at `getprobo/homebrew-tap`. diff --git a/contrib/claude/release/probod-bootstrap.md b/contrib/claude/release/probod-bootstrap.md index 1872a7bd2..c0dcfa2b2 100644 --- a/contrib/claude/release/probod-bootstrap.md +++ b/contrib/claude/release/probod-bootstrap.md @@ -1,44 +1,30 @@ # Release `probod-bootstrap` -Entrypoint for releasing `probod-bootstrap`. Read [README.md](./README.md) -first for overall flow, changelog rules, and the non-empty-track -guarantee. +After confirming commits below, follow the +[common steps](./README.md#3-common-steps-every-track). ## Track facts - **Tag pattern**: `probod-bootstrap/v*` -- **Version source**: `cmd/probod-bootstrap/VERSION` (contains only `X.Y.Z`) +- **Version source**: `cmd/probod-bootstrap/VERSION` (single `X.Y.Z` line) +- **Version bump**: Edit `cmd/probod-bootstrap/VERSION` directly - **Changelog**: `cmd/probod-bootstrap/CHANGELOG.md` +- **Files to stage**: `cmd/probod-bootstrap/VERSION`, + `cmd/probod-bootstrap/CHANGELOG.md` - **Workflow**: `.github/workflows/release-probod-bootstrap.yaml` -- **Path filter** (for log/scoping): `cmd/probod-bootstrap` +- **Path filter**: `cmd/probod-bootstrap` -## Steps +## Detect commits -1. From a clean `main`, list commits since the last `probod-bootstrap` - tag: +```shell +git log $(git describe --tags --abbrev=0 --match='probod-bootstrap/v*')..HEAD --oneline \ + -- cmd/probod-bootstrap +``` - ```shell - git log $(git describe --tags --abbrev=0 --match='probod-bootstrap/v*')..HEAD --oneline \ - -- cmd/probod-bootstrap - ``` +If empty or non-user-facing only, do not release this track. - If the list is empty (or contains only non-user-facing commits), do - not release this track. +## Notes -2. Decide the version bump (PATCH for fixes, MINOR for features). -3. Bump the version in `cmd/probod-bootstrap/VERSION`. -4. Write the new entry in `cmd/probod-bootstrap/CHANGELOG.md` following - the rules in [README.md](./README.md#2-writing-a-changelog-entry). -5. Show the user the changelog diff and the new version. Wait for - confirmation. -6. Stage only `cmd/probod-bootstrap/VERSION` and - `cmd/probod-bootstrap/CHANGELOG.md`. Commit subject: - `Release probod-bootstrap/v`. No body. -7. Annotated tag: - `git tag -a probod-bootstrap/v -m "probod-bootstrap/v"`. -8. Push: `git push origin main --follow-tags`. - -CI workflow `release-probod-bootstrap.yaml` builds binaries for 9 OS/arch -targets and publishes a GitHub Release. Note: the same binary, built -from the tagged ref, is also bundled into the probod Docker image when -`probod/v*` runs. +CI builds binaries for 9 OS/arch targets and publishes a GitHub Release. +The same binary, built from the tagged ref, is also bundled into the +probod Docker image when `probod/v*` runs. diff --git a/contrib/claude/release/probod.md b/contrib/claude/release/probod.md index e96c39bf6..438567fdd 100644 --- a/contrib/claude/release/probod.md +++ b/contrib/claude/release/probod.md @@ -1,48 +1,37 @@ # Release `probod` (server group) -Entrypoint for releasing the `probod` server group. Read -[README.md](./README.md) first for overall flow, changelog rules, and the -non-empty-track guarantee. - This track ships `probod`, `@probo/console`, `@probo/trust`, and `@probo/ui` together as the Docker image and accompanying binary archive. They share the same version. +After confirming commits below, follow the +[common steps](./README.md#3-common-steps-every-track). + ## Track facts - **Tag pattern**: `probod/v*` -- **Version source**: `cmd/probod/VERSION` (contains only `X.Y.Z`) +- **Version source**: `cmd/probod/VERSION` (single `X.Y.Z` line) +- **Version bump**: Edit `cmd/probod/VERSION` directly - **Changelog**: `cmd/probod/CHANGELOG.md` (covers all four components) +- **Files to stage**: `cmd/probod/VERSION`, `cmd/probod/CHANGELOG.md` - **Workflow**: `.github/workflows/release-probod.yaml` -- **Path filter** (for log/scoping): - `cmd/probod apps/console apps/trust packages/ui pkg` +- **Path filter**: `cmd/probod apps/console apps/trust packages/ui pkg` -## Steps +## Detect commits -1. From a clean `main`, list commits since the last `probod` tag: +```shell +git log $(git describe --tags --abbrev=0 --match='probod/v*')..HEAD --oneline \ + -- cmd/probod apps/console apps/trust packages/ui pkg +``` - ```shell - git log $(git describe --tags --abbrev=0 --match='probod/v*')..HEAD --oneline \ - -- cmd/probod apps/console apps/trust packages/ui pkg - ``` +If empty or non-user-facing only, do not release this track. - If the list is empty (or contains only non-user-facing commits), do - not release this track. +## Notes -2. Decide the version bump (PATCH for fixes, MINOR for features). -3. Bump the version in `cmd/probod/VERSION`. -4. Write the new entry in `cmd/probod/CHANGELOG.md` covering changes - across `probod`, `@probo/console`, `@probo/trust`, and `@probo/ui`. - Follow the rules in - [README.md](./README.md#2-writing-a-changelog-entry). -5. Show the user the changelog diff and the new version. Wait for - confirmation. -6. Stage only `cmd/probod/VERSION` and `cmd/probod/CHANGELOG.md`. - Commit subject: `Release probod/v`. No body. -7. Annotated tag: `git tag -a probod/v -m "probod/v"`. -8. Push: `git push origin main --follow-tags`. +The changelog covers changes across all four components (`probod`, +`@probo/console`, `@probo/trust`, `@probo/ui`). -CI workflow `release-probod.yaml` builds the frontends, builds the Go -binaries, builds and pushes the multi-arch image to -`ghcr.io/getprobo/probo:probod-v` (and `:latest`), runs Trivy + -cosign + attestations, and publishes the GitHub Release. +CI builds the frontends and Go binaries, builds and pushes the +multi-arch image to `ghcr.io/getprobo/probo:probod-v` (and +`:latest`), runs Trivy + cosign + attestations, and publishes the GitHub +Release.