Skip to content

Commit 78a26a1

Browse files
committed
docs(release): add release docs PR step
1 parent c8c3926 commit 78a26a1

2 files changed

Lines changed: 166 additions & 0 deletions

File tree

‎.roo/commands/release.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,3 +110,55 @@ mode: code
110110
111111
- Do not merge before the deployment succeeds — merging first and then discovering a publish failure leaves `main` ahead of what was actually shipped.
112112
- The merge queue runs all required checks against the release branch before merging to `main`.
113+
114+
15. As the final stable extension release step, open a separate documentation PR in `Zoo-Code-Org/Zoo-Code-Docs`.
115+
116+
- Run this step only after the marketplace workflow for the exact stable tag has succeeded, the corresponding GitHub release exists, and step 14 has added the Zoo Code release PR to the merge queue. This step does not apply to nightly, CLI, npm, or types releases.
117+
- Retain the exact Zoo Code changelog section, complete merged-PR inventory, release PR URL, tag and GitHub release URL, marketplace workflow URL, successful publication timestamp, and release PR merge-queue state as inputs to the docs work and final report.
118+
119+
**Preflight and checkout**
120+
121+
- Verify local GitHub authentication and access and push permission for `Zoo-Code-Org/Zoo-Code-Docs` (for example, with `gh auth status`, `gh repo view`, and an authenticated permission query). Do not assume or claim that `GITHUB_TOKEN` has cross-repository access.
122+
- Prefer the portable sibling checkout `../Zoo-Code-Docs`. If it is absent, create a clean temporary directory and clone `https://github.com/Zoo-Code-Org/Zoo-Code-Docs.git` there. Do not modify the docs repository from the Zoo Code checkout.
123+
- In an existing checkout, read `AGENTS.md` and `.roorules` when present, abort if the worktree is dirty, verify `origin` is `Zoo-Code-Org/Zoo-Code-Docs` and its default branch is `main`, fetch `origin`, switch to local `main`, and fast-forward it only to the exact `origin/main` with `git merge --ff-only origin/main`. Never stash or reset work, and never change remotes. The fallback clone must likewise use `origin/main` as its clean base.
124+
125+
**Idempotency and branch safety**
126+
127+
- Use the deterministic branch `docs/release-v[version]`. Before creating or pushing anything, query the local branch, the remote branch, and all matching open, closed, and merged PRs in the target repository; validate the repository, `main` base, head branch, commit history, and content.
128+
- A matching merged PR with the expected content means this step is complete. Reuse and validate a matching open PR. Inspect and reuse a branch without a PR only when its commits and content are clearly the expected release-docs work.
129+
- Abort on a closed-unmerged PR, wrong repository or base, local/remote divergence, unexpected commits, a version conflict, or ambiguous state. Never force-push blindly, stop on any remote race, and never downgrade a docs `package.json` version that is newer than the released version.
130+
131+
**Documentation and version synchronization**
132+
133+
- Always assess and create or update `docs/update-notes/v[version].md`, register that exact version newest-first in both `docs/update-notes/index.md` and `sidebars.ts`, and use the stable publication date, Zoo Code branding, and the docs project's existing linking conventions.
134+
- Build a per-PR documentation impact matrix from every shipped PR. Cover every user-visible change in the release note, and update all relevant canonical evergreen provider, feature, tool, and getting-started pages. Record a rationale for each implementation-only exclusion and, when no evergreen page changes are needed, record that no-change rationale.
135+
- Synchronize the docs repository's sole package version in `package.json` using exactly:
136+
137+
```bash
138+
pnpm version "$VERSION" --no-git-tag-version --allow-same-version
139+
```
140+
141+
Confirm this creates no tag and no incidental `pnpm-lock.yaml` change.
142+
143+
**Validation and PR creation**
144+
145+
- From the docs checkout, run all of these commands successfully:
146+
147+
```bash
148+
mise install
149+
pnpm install --frozen-lockfile
150+
pnpm run check-types
151+
pnpm run lint
152+
pnpm run lint:unused
153+
pnpm run build
154+
git diff --check
155+
```
156+
157+
- Inspect build warnings explicitly. Block the PR on newly introduced broken-link, document, MDX, sidebar, or content warnings. Verify the changed and staged scope contains only intended source files and no generated output.
158+
- Commit as `docs(release): document v[version]`, push normally (never force-push) to `docs/release-v[version]`, and stop rather than overwrite a remote race.
159+
- Open or reuse a PR in `Zoo-Code-Org/Zoo-Code-Docs` with base `main` and title `[Docs] Update documentation for Zoo Code v[version]`. Its body must include the source release and tag, Zoo Code release PR, marketplace workflow and successful publication timestamp, summary, package version synchronization, per-PR impact matrix and exclusions, evergreen changes or no-change rationale, validation results and warning review, and an explicit statement that this is a separate docs PR and will not be auto-merged. Never enable auto-merge for this PR.
160+
161+
**Reporting and partial failure**
162+
163+
- Docs failure cannot roll back or invalidate the published extension. A failure report must begin: `Zoo Code v[version] is already published and docs PR completion is pending.` Then report the failed checkpoint, checkout path, branch, PR URL/state when present, failure details, and the safe recovery action.
164+
- The final release report must include release/tag/workflow URLs and the successful publication timestamp, the Zoo Code release PR merge-queue state, docs PR URL/state, docs branch and commit SHA, package-version synchronization status, release-note/index/sidebar status, evergreen documentation status, validation results and inspected warnings, and confirmation that the separate docs PR was not auto-merged.
Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
import fs from "node:fs"
2+
import path from "node:path"
3+
import { fileURLToPath } from "node:url"
4+
5+
const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..")
6+
const releaseCommand = fs.readFileSync(path.join(repositoryRoot, ".roo/commands/release.md"), "utf8")
7+
const topLevelSteps = [...releaseCommand.matchAll(/^(\d+)\. .+$/gm)]
8+
const finalStepStart = topLevelSteps.find((step) => step[1] === "15")?.index ?? -1
9+
const finalStep = releaseCommand.slice(finalStepStart)
10+
11+
describe("stable release command documentation handoff", () => {
12+
it("keeps the docs PR as final step 15 after publication and the release merge queue", () => {
13+
expect(topLevelSteps.map((step) => Number(step[1])).at(-1)).toBe(15)
14+
expect(finalStepStart).toBeGreaterThan(releaseCommand.indexOf("14. After a successful deployment"))
15+
expect(finalStep).toMatch(/only after[\s\S]*marketplace workflow[\s\S]*exact stable tag[\s\S]*succeeded/i)
16+
expect(finalStep).toMatch(/GitHub release exists/i)
17+
expect(finalStep).toMatch(/step 14[\s\S]*merge queue/i)
18+
expect(finalStep).toMatch(/final stable extension release step/i)
19+
expect(finalStep).toMatch(/does not apply to nightly, CLI, npm, or types releases/i)
20+
})
21+
22+
it("targets a separate Zoo-Code-Docs PR with the required branch and PR conventions", () => {
23+
expect(finalStep).toContain("Zoo-Code-Org/Zoo-Code-Docs")
24+
expect(finalStep).toContain("docs/release-v[version]")
25+
expect(finalStep).toContain("docs(release): document v[version]")
26+
expect(finalStep).toContain("[Docs] Update documentation for Zoo Code v[version]")
27+
expect(finalStep).toMatch(/base `main`/i)
28+
expect(finalStep).toMatch(/separate docs PR[\s\S]*will not be auto-merged/i)
29+
expect(finalStep).toMatch(/Never enable auto-merge/i)
30+
})
31+
32+
it("requires release notes, navigation registration, and evergreen documentation review", () => {
33+
expect(finalStep).toContain("docs/update-notes/v[version].md")
34+
expect(finalStep).toContain("docs/update-notes/index.md")
35+
expect(finalStep).toContain("sidebars.ts")
36+
expect(finalStep).toMatch(/newest-first/i)
37+
expect(finalStep).toMatch(/per-PR documentation impact matrix/i)
38+
expect(finalStep).toMatch(/every user-visible change/i)
39+
expect(finalStep).toMatch(/canonical evergreen provider, feature, tool, and getting-started pages/i)
40+
expect(finalStep).toMatch(/implementation-only exclusion/i)
41+
expect(finalStep).toMatch(/no-change rationale/i)
42+
})
43+
44+
it("synchronizes the sole docs package version without tags or lockfile drift", () => {
45+
expect(finalStep).toContain('pnpm version "$VERSION" --no-git-tag-version --allow-same-version')
46+
expect(finalStep).toMatch(/sole package version in `package\.json`/i)
47+
expect(finalStep).toMatch(/no tag/i)
48+
expect(finalStep).toMatch(/no incidental `pnpm-lock\.yaml` change/i)
49+
expect(finalStep).toMatch(/never downgrade/i)
50+
})
51+
52+
it("protects existing checkouts and establishes an exact clean origin/main base", () => {
53+
expect(finalStep).toContain("../Zoo-Code-Docs")
54+
expect(finalStep).toContain("https://github.com/Zoo-Code-Org/Zoo-Code-Docs.git")
55+
expect(finalStep).toMatch(/clean temporary directory/i)
56+
expect(finalStep).toMatch(/read `AGENTS\.md` and `\.roorules`/i)
57+
expect(finalStep).toMatch(/abort if the worktree is dirty/i)
58+
expect(finalStep).toMatch(/verify `origin`[\s\S]*default branch is `main`/i)
59+
expect(finalStep).toContain("git merge --ff-only origin/main")
60+
expect(finalStep).toMatch(/Never stash or reset[\s\S]*never change remotes/i)
61+
})
62+
63+
it("handles merged, open, and branch-only prior attempts without unsafe pushes", () => {
64+
expect(finalStep).toMatch(
65+
/query the local branch, the remote branch, and all matching open, closed, and merged PRs/i,
66+
)
67+
expect(finalStep).toMatch(/matching merged PR[\s\S]*complete/i)
68+
expect(finalStep).toMatch(/Reuse and validate a matching open PR/i)
69+
expect(finalStep).toMatch(/branch without a PR only when[\s\S]*expected release-docs work/i)
70+
expect(finalStep).toMatch(/closed-unmerged PR[\s\S]*wrong repository or base[\s\S]*divergence/i)
71+
expect(finalStep).toMatch(/Never force-push blindly/i)
72+
expect(finalStep).toMatch(/stop on any remote race/i)
73+
})
74+
75+
it("runs every docs validation and blocks on newly introduced content warnings", () => {
76+
const validationCommands = [
77+
"mise install",
78+
"pnpm install --frozen-lockfile",
79+
"pnpm run check-types",
80+
"pnpm run lint",
81+
"pnpm run lint:unused",
82+
"pnpm run build",
83+
"git diff --check",
84+
]
85+
86+
for (const command of validationCommands) expect(finalStep).toContain(command)
87+
expect(finalStep).toMatch(/Inspect build warnings explicitly/i)
88+
expect(finalStep).toMatch(
89+
/Block the PR on newly introduced broken-link, document, MDX, sidebar, or content warnings/i,
90+
)
91+
expect(finalStep).toMatch(/changed and staged scope[\s\S]*no generated output/i)
92+
})
93+
94+
it("verifies local auth and permissions without assuming cross-repository token access", () => {
95+
expect(finalStep).toContain("gh auth status")
96+
expect(finalStep).toMatch(/access and push permission/i)
97+
expect(finalStep).toMatch(/Do not assume or claim that `GITHUB_TOKEN` has cross-repository access/i)
98+
})
99+
100+
it("retains source metadata and specifies partial-failure and final reporting", () => {
101+
expect(finalStep).toMatch(/exact Zoo Code changelog section/i)
102+
expect(finalStep).toMatch(/complete merged-PR inventory/i)
103+
expect(finalStep).toMatch(
104+
/release PR URL[\s\S]*GitHub release URL[\s\S]*workflow URL[\s\S]*publication timestamp/i,
105+
)
106+
expect(finalStep).toMatch(/Docs failure cannot roll back or invalidate the published extension/i)
107+
expect(finalStep).toContain("Zoo Code v[version] is already published and docs PR completion is pending.")
108+
expect(finalStep).toMatch(/failed checkpoint, checkout path, branch, PR URL\/state[\s\S]*safe recovery action/i)
109+
expect(finalStep).toMatch(/final release report[\s\S]*release\/tag\/workflow URLs/i)
110+
expect(finalStep).toMatch(/docs PR URL\/state[\s\S]*docs branch and commit SHA/i)
111+
expect(finalStep).toMatch(/release-note\/index\/sidebar status[\s\S]*evergreen documentation status/i)
112+
expect(finalStep).toMatch(/confirmation that the separate docs PR was not auto-merged/i)
113+
})
114+
})

0 commit comments

Comments
 (0)