Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -207,4 +207,4 @@ whose reusables live in this repo, `feature-ideation`'s reusable lives in **`pet
(this repo holds only the thin caller stub), so its release/channel tags are cut against that public
repo — and the protective ruleset bounding `feature-ideation/**` channel tags is therefore created
**there**, not on this repo (an untracked prerequisite in the public repo). See
[`docs/release/versioning.md`](./docs/release/versioning.md) "Cross-repo: feature-ideation".
[`docs/release/versioning.md`](./docs/release/versioning.md) "Cross-repo reusables".
40 changes: 23 additions & 17 deletions docs/release/runbook.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,17 @@ Operational procedures for the per-agent channel-tag release model (initiative
[`versioning.md`](./versioning.md) and the
[initiative analysis](../initiatives/agentic-release-strategy.md) §5.1, §7.

**Agents covered:** `pr-review`, `dev-lead`, `feature-ideation`. `pr-review` and
**Agents covered:** `pr-review`, `dev-lead`, `feature-ideation`, and the six #482
reusables (`agent-shield`, `auto-rebase`, `dependency-audit`,
`dependabot-automerge`, `dependabot-rebase`, `pr-review-mention`). `pr-review` and
`dev-lead` live in this repo; callers (consumers + this repo's own self-host
caller) pin the moving channel tag `@<agent>/stable` and thread
`agent_ref: <agent>/stable`. `feature-ideation`'s reusable lives in
`petry-projects/.github`, so its release/channel tags are cut against **that**
repo, not this repo's `origin` (see "Cross-repo: feature-ideation" in
[`versioning.md`](./versioning.md)). `cut-release.sh` recognizes it and previews
its tags via `--dry-run`, but **live cross-repo pushes are not wired yet** — the
push target is an open question, so non-dry-run cuts for `feature-ideation` are
`agent_ref: <agent>/stable`. The cross-repo reusables (`feature-ideation` + the
six above) live in `petry-projects/.github`, so their release/channel tags are cut
against **that** repo, not this repo's `origin` (see "Cross-repo reusables" in
[`versioning.md`](./versioning.md)). `cut-release.sh` recognizes them and previews
their tags via `--dry-run`, but **live cross-repo pushes are not wired yet** — the
push target is an open question, so non-dry-run cuts for any cross-repo agent are
refused for now.

**Two tag kinds per agent:**
Expand Down Expand Up @@ -56,10 +58,12 @@ scripts/cut-release.sh pr-review 1.6.0 --ref origin/main --dry-run
# Cut the immutable tag only (no promotion):
scripts/cut-release.sh pr-review 1.6.0 --ref origin/main --push

# feature-ideation is cross-repo (reusable in petry-projects/.github): dry-run
# previews the tag names, but live --push is refused until the cross-repo target
# is decided (see "Cross-repo: feature-ideation" in versioning.md):
# Cross-repo agents (feature-ideation + the six #482 reusables, reusables in
# petry-projects/.github): dry-run previews the tag names, but live --push is
# refused until the cross-repo target is decided (see "Cross-repo reusables" in
# versioning.md):
scripts/cut-release.sh feature-ideation 1.4.0 --channel ring0 --dry-run
scripts/cut-release.sh agent-shield 2.1.0 --channel next --dry-run
```

- Pick the version per semver (see `versioning.md#semantic-versioning`): bugfix →
Expand Down Expand Up @@ -104,11 +108,13 @@ git push origin pr-review/stable --force
> Channel tags are lightweight (point straight at the commit); the immutable
> `vX.Y.Z` tags are annotated.
>
> **feature-ideation is cross-repo.** Its `feature-ideation/<channel>` tags live
> **Cross-repo agents.** `feature-ideation` and the six #482 reusables
> (`agent-shield`, `auto-rebase`, `dependency-audit`, `dependabot-automerge`,
> `dependabot-rebase`, `pr-review-mention`) have `<agent>/<channel>` tags that live
> on `petry-projects/.github`, so a promotion is a tag move on **that** repo
> (`git push <petry-projects/.github remote> feature-ideation/<channel> --force`),
> not this repo's `origin`. The exact remote/target for the automated path is an
> open question — `cut-release.sh` refuses a live `feature-ideation` cut until it
> (`git push <petry-projects/.github remote> <agent>/<channel> --force`), not this
> repo's `origin`. The exact remote/target for the automated path is an open
> question — `cut-release.sh` refuses a live cut for any cross-repo agent until it
> is resolved; preview with `--dry-run`.

Then **verify** (§4).
Expand Down Expand Up @@ -184,9 +190,9 @@ git push origin pr-review/stable --force

- The immutable `vX.Y.Z` tags are the rollback targets — pick the last release
known healthy (`git tag -l 'pr-review/v*' | sort -V`).
- For `feature-ideation`, the same reverse-tag-move applies but against
`petry-projects/.github` (where its `feature-ideation/v*` and channel tags
live), not this repo — see the cross-repo note in §2b.
- For the cross-repo agents (`feature-ideation` + the six #482 reusables), the
same reverse-tag-move applies but against `petry-projects/.github` (where their
`<agent>/v*` and channel tags live), not this repo — see the cross-repo note in §2b.
- Every caller picks up the rolled-back version on its **next** run with no
change on their side. In-flight runs already started on the bad version finish;
new runs use the restored one.
Expand Down
77 changes: 56 additions & 21 deletions docs/release/versioning.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,16 @@ together, so a version is a single repo commit that contains a known-good combin
| `pr-review` | `.github/workflows/pr-review.yml` | `scripts/review-one-pr.sh`, `scripts/review-batch.sh`, `scripts/post-pr-review.sh`, `scripts/engine.sh`, `scripts/lib/*` |
| `dev-lead` | `.github/workflows/dev-lead-reusable.yml` | `scripts/dev-lead-*.sh`, `scripts/engine.sh`, `scripts/lib/*` |
| `feature-ideation` | `petry-projects/.github` → `.github/workflows/feature-ideation-reusable.yml` (**cross-repo**) | reusable-owned (lives in the public repo; this repo holds only the thin caller `.github/workflows/feature-ideation.yml`) |
| `agent-shield`, `auto-rebase`, `dependency-audit`, `dependabot-automerge`, `dependabot-rebase`, `pr-review-mention` (the six #482 reusables) | `petry-projects/.github` → `.github/workflows/<name>-reusable.yml` (**cross-repo**) | reusable-owned (live in the public repo; this repo holds only the thin caller stubs) |

`pr-review` and `dev-lead` both live in this repo, so a release tag points at a whole-repo commit; the
tag *name* scopes it to one agent so the two can be released and promoted independently.

`feature-ideation` is the exception: its reusable lives in **`petry-projects/.github`** (this repo holds
only the thin caller stub), so a `feature-ideation` "release" is a commit on that public repo, and its
release/channel tags must be cut **against `petry-projects/.github`, not this repo's `origin`**. See
[Cross-repo: feature-ideation](#cross-repo-feature-ideation) below.
The rest are the exception: their reusables live in **`petry-projects/.github`** (this repo holds only
the thin caller stubs), so a "release" is a commit on that public repo, and their release/channel tags
must be cut **against `petry-projects/.github`, not this repo's `origin`**. This is `feature-ideation`
plus the six reusables #482 migrated to channel tags — see [Cross-repo reusables](#cross-repo-reusables)
below.

## Tag scheme

Expand Down Expand Up @@ -79,7 +81,22 @@ uses `stable` only; its ring channels are pending under #499.
promoted through the same canary → ring → stable model. Its tags follow the identical name scheme
(`feature-ideation/vX.Y.Z`, `feature-ideation/next`, `feature-ideation/ring0`,
`feature-ideation/ring1`, `feature-ideation/stable`) but are cut against `petry-projects/.github`
(see [Cross-repo: feature-ideation](#cross-repo-feature-ideation)).
(see [Cross-repo reusables](#cross-repo-reusables)).

The six **#482 reusables** — `agent-shield`, `auto-rebase`, `dependency-audit`, `dependabot-automerge`,
`dependabot-rebase`, `pr-review-mention` — use the same `{next, ring0, ring1, stable}` set (#870),
replacing the single-hop `<name>/stable`-only migration #482 cut by hand. They are `.github`-hosted, so
like `feature-ideation` their tags are cut against `petry-projects/.github`. Their ring membership is an
**explicit org-owner assignment** (#870, matching #866), and it does **not** follow the host-relative
`$host`/`$org_infra` default above — `next` is `.github-private` (the dogfood lab) even though the
reusables are hosted in `.github`, which sits in `ring0`:

| Channel | Member repo(s) |
|---|---|
| `next` | `.github-private` |
| `ring0` | `.github` (the host) |
| `ring1` | `TalkTerm`, `bmad-bgreat-suite` |
| `stable` | `markets`, `broodly`, `ContentTwin`, `google-app-scripts` (full-fleet production) |

### Semantic versioning

Expand Down Expand Up @@ -114,28 +131,46 @@ The first release was cut from the production `main` at the time of issue #496:
version. The health-gated promotion added in Phase 2 (#501) is what makes *future* promotions to
`stable` genuinely validated before they become production.

## Cross-repo: feature-ideation
## Cross-repo reusables

Everything above assumes the agent's reusable workflow lives **in this repo**, so a release tag is a
whole-repo commit here and tags are cut against this repo's `origin`. That holds for `pr-review` and
`dev-lead`. It does **not** hold for `feature-ideation`:

- `feature-ideation`'s reusable lives in **`petry-projects/.github`**
(`.github/workflows/feature-ideation-reusable.yml`); this repo carries only the thin caller stub
`.github/workflows/feature-ideation.yml`.
- Therefore a `feature-ideation` release is a commit on **`petry-projects/.github`**, and its
`feature-ideation/vX.Y.Z` immutable + `feature-ideation/<channel>` tags must be cut **against that
repo**, not this repo's `origin`.
- `scripts/cut-release.sh` already recognizes `feature-ideation` and formats its tag names, and its
`--dry-run` prints the intended immutable + channel tags. **Live cross-repo pushes are not wired
yet** — the push target mechanism (a `--repo`/remote argument vs. dispatching against the public
`dev-lead`. It does **not** hold for the cross-repo reusables — `feature-ideation` and the six #482
reusables (`agent-shield`, `auto-rebase`, `dependency-audit`, `dependabot-automerge`,
`dependabot-rebase`, `pr-review-mention`):

- Their reusables live in **`petry-projects/.github`** (`.github/workflows/<name>-reusable.yml`); this
repo carries only the thin caller stubs `.github/workflows/<name>.yml`.
- Therefore a release is a commit on **`petry-projects/.github`**, and the `<name>/vX.Y.Z` immutable +
`<name>/<channel>` tags must be cut **against that repo**, not this repo's `origin`.
- `scripts/cut-release.sh` recognizes each of these agents (`valid_agent`) and formats its tag names,
and its `--dry-run` prints the intended immutable + channel tags. **Live cross-repo pushes are not
wired yet** — the push target mechanism (a `--repo`/remote argument vs. dispatching against the public
repo) is an open question reserved for a human decision, so the script refuses a non-dry-run cut for
`feature-ideation` (see the `TODO(#872)` in `cut-release.sh`). Use `--dry-run` to preview tag names
until the target is decided.
- Because `feature-ideation`'s channel tags live on `petry-projects/.github`, the protective ruleset
that bounds them (the mutable-ref exception) is created **there**, not on this repo — see
any cross-repo agent (the `cross_repo_agent` guard / `TODO(#872)` in `cut-release.sh`). Use
`--dry-run` to preview tag names until the target is decided.
- Because these channel tags live on `petry-projects/.github`, the protective ruleset that bounds them
(the mutable-ref exception) is created **there**, not on this repo — see
[`AGENTS.md`](../../AGENTS.md) "Release channel tags & the mutable-ref exception".

> **Why not `standards/canary-rings.json` yet?** The machine-readable ring source of truth consumed by
> the promotion automation (`scripts/canary-rollout.sh`, #501) carries only the in-repo agents whose
> channel tags it can actually move. Cross-repo agents (`feature-ideation` and the six above) are
> documented here and supported by `cut-release.sh` (dry-run), but are deliberately **absent** from
> `canary-rings.json` until the cross-repo tag-move path is wired (`TODO #872`) — adding them sooner
> would advertise a promotion the automation cannot perform.

### The six #482 reusables (ring assignment)

PR #482 migrated these six to moving channel tags **single-hop** — it cut only `<name>/stable` (+ a manual
off-convention `<name>/v2.0.0`) and put all consumers on `stable`, with no `next`/`ring*`. #870 brings
them under the full `{next, ring0, ring1, stable}` model with the explicit, org-owner ring assignment in
[Ring channels](#ring-channels-live-for-dev-lead) above. Note this assignment is **explicit, not
host-relative**: `next` is `.github-private` even though the reusables are hosted in `.github` (which
sits in `ring0`). Re-cutting their releases on a sane incremental-semver basis (reconciling the manual
`<name>/v2.0.0` tags) and cutting the `next`/`ring0`/`ring1` channels is an operational step done via
`cut-release.sh` once the cross-repo push target (`TODO #872`) is wired.

## Cutting / moving tags

Use `scripts/cut-release.sh` (tested in `tests/test_cut_release.bats`) rather than ad-hoc `git tag`:
Expand Down
55 changes: 38 additions & 17 deletions scripts/cut-release.sh
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,10 @@
# cut-release.sh <agent> <version> [--ref <ref>] [--channel <name>]
# [--push] [--dry-run]
#
# <agent> pr-review | dev-lead | feature-ideation
# <agent> this repo: pr-review | dev-lead
# cross-repo (reusable in petry-projects/.github): feature-ideation |
# agent-shield | auto-rebase | dependency-audit |
# dependabot-automerge | dependabot-rebase | pr-review-mention
# <version> semantic version without the leading v, e.g. 1.2.0
# --ref commit/ref to tag (default: origin/main)
# --channel also move <agent>/<name> (e.g. stable) to the new release
Expand All @@ -21,18 +24,36 @@
# cut-release.sh pr-review 1.1.0 --channel stable --push
# cut-release.sh dev-lead 2.0.0 --channel stable --dry-run
#
# The pure helpers (valid_agent, validate_version, release_ref, channel_ref) are
# defined at the top level so tests can `source` this file without executing it
# (see the source-guard at the bottom and tests/test_cut_release.bats).
# The pure helpers (valid_agent, cross_repo_agent, validate_version, release_ref,
# channel_ref) are defined at the top level so tests can `source` this file without
# executing it (see the source-guard at the bottom and tests/test_cut_release.bats).
#
set -euo pipefail

# ── pure helpers (sourced by tests; no side effects) ─────────────────────────

# valid_agent <agent> — return 0 iff agent is a known agent name.
# valid_agent <agent> — return 0 iff agent is a known agent name. Covers the two
# agents hosted in this repo (pr-review, dev-lead) plus the cross-repo reusables
# hosted in petry-projects/.github (feature-ideation and the six #482 reusables
# brought under the ring model in #870).
valid_agent() {
case "$1" in
pr-review | dev-lead | feature-ideation) return 0 ;;
pr-review | dev-lead) return 0 ;;
*) cross_repo_agent "$1" ;;
esac
}

# cross_repo_agent <agent> — return 0 iff the agent's reusable workflow lives in
# petry-projects/.github (this repo holds only the thin caller stub). For these,
# a "release" is a commit on that public repo, so its release/channel tags must be
# cut against THAT repo — not this repo's `origin`. The cross-repo push target is
# an open question (TODO #872), so live cuts are refused and only --dry-run is
# supported. See docs/release/versioning.md "Cross-repo reusables".
cross_repo_agent() {
case "$1" in
feature-ideation) return 0 ;;
agent-shield | auto-rebase | dependency-audit) return 0 ;;
dependabot-automerge | dependabot-rebase | pr-review-mention) return 0 ;;
*) return 1 ;;
esac
}
Expand Down Expand Up @@ -75,7 +96,7 @@ main() {
done

if ! valid_agent "$agent"; then
echo "::error::unknown agent '$agent' (expected: pr-review | dev-lead | feature-ideation)" >&2
echo "::error::unknown agent '$agent' (expected: pr-review | dev-lead | feature-ideation | agent-shield | auto-rebase | dependency-audit | dependabot-automerge | dependabot-rebase | pr-review-mention)" >&2
return 2
fi
if ! validate_version "$version"; then
Expand All @@ -95,21 +116,21 @@ main() {
[ -n "$channel" ] && { chan="$(channel_ref "$agent" "$channel")"; echo "channel tag: $chan -> $rel"; }

if [ "$dry" = true ]; then
if [ "$agent" = "feature-ideation" ]; then
echo "::warning::cross-repo placeholder: the SHA above ($sha) was resolved from petry-projects/.github-private. feature-ideation's canonical commits and tags live in petry-projects/.github — this SHA is a local placeholder only."
if cross_repo_agent "$agent"; then
echo "::warning::cross-repo placeholder: the SHA above ($sha) was resolved from petry-projects/.github-private. ${agent}'s canonical commits and tags live in petry-projects/.github — this SHA is a local placeholder only."
fi
echo "(dry-run) no tags created or pushed."
return 0
fi

# TODO(#872): feature-ideation's reusable lives in petry-projects/.github, so its
# release/channel tags must be cut against THAT repo — but main() pushes to this
# repo's `origin`. The cross-repo push target (a --repo/remote arg vs. dispatching
# against the public repo) is an open question reserved for a human decision. Until
# it is wired, only --dry-run is supported for feature-ideation; refuse live cuts so
# tags are never written to the wrong remote.
if [ "$agent" = "feature-ideation" ]; then
echo "::error::live cut/push for 'feature-ideation' is not wired yet — its tags belong on petry-projects/.github (cross-repo target is an open question; see TODO). Use --dry-run for now." >&2
# TODO(#872): the cross-repo agents' reusables live in petry-projects/.github, so
# their release/channel tags must be cut against THAT repo — but main() pushes to
# this repo's `origin`. The cross-repo push target (a --repo/remote arg vs.
# dispatching against the public repo) is an open question reserved for a human
# decision. Until it is wired, only --dry-run is supported for these agents; refuse
# live cuts so tags are never written to the wrong remote.
if cross_repo_agent "$agent"; then
echo "::error::live cut/push for '$agent' is not wired yet — its tags belong on petry-projects/.github (cross-repo target is an open question; see TODO). Use --dry-run for now." >&2
return 1
fi

Expand Down
Loading
Loading