review: keep the pinned review.md ref in sync with the released version#242
Conversation
…sync with the released version The pre-agent-steps checkout ref in review.md is supposed to name the release the file ships in, but changesets only bumps package.json, so every tag since review-v1.2.2 shipped with a stale ref (and v1.4.0's prompt invokes lib/provenance.ts, which a v1.2.2 checkout lacks). The release flow's version command now runs utils/sync-review-version.ts after changeset version, rewriting every review-v<semver> literal in review.md to the version being released so the bump lands in the same Version Packages commit that gets tagged. version-sync.test.ts is the CI backstop: it fails any PR where the ref diverges from the review package version. Also bumps the currently stale ref to review-v1.4.0.
🦋 Changeset detectedLatest commit: 3eafaab The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
khan-actions-bot
requested review from
a team,
kevinb-khan and
somewhatabstract
and removed request for
a team
jeresig
left a comment
jeresig
left a comment
There was a problem hiding this comment.
Thanks for solving this issue - one request inline to make this generic for any possible workflow that we add!
| if: steps.has-changesets.outputs.result == 'true' | ||
| uses: changesets/action@6a0a831ff30acef54f2c6aa1cbbc1096b066edaf # v1 | ||
| with: | ||
| # Not the default `changeset version`: version-packages also syncs |
There was a problem hiding this comment.
| # Not the default `changeset version`: version-packages also syncs | |
| # Note the default `changeset version`: version-packages also syncs |
There was a problem hiding this comment.
Reworded this comment as part of making the sync generic; it now leads with what version-packages does rather than the "Not the default" phrasing.
| @@ -0,0 +1,79 @@ | |||
| import * as fs from "fs"; | |||
There was a problem hiding this comment.
Could we make this generic so that it updates any workflow? We're bound to have more shared workflows so we might as well handle this in a single way.
There was a problem hiding this comment.
Done in 3eafaab: the script is now utils/sync-workflow-versions.ts. It discovers every directory under workflows/ (the tag is named after the directory, matching publishWorkflow in utils/publish.ts), reads its package.json version, and rewrites every <name>-v<semver> literal in that workflow's markdown files, skipping CHANGELOG.md since changesets writes historic versions there on purpose. A workflow whose markdown embeds no literal is a no-op; a workflow that must embed one (like review.md's checkout ref) keeps its own contract test as the CI backstop.
…eric across workflows Review feedback on #242: instead of a review-only script, discover every workflow under workflows/ and rewrite its <name>-v<semver> literals (tag names come from the directory name, matching publishWorkflow) in its markdown files, skipping CHANGELOG.md. A workflow with no literals is a no-op; per-workflow contract tests (workflows/review/version-sync.test.ts) remain the CI backstop.
2 participants
Problem: the ref: lag
workflows/review/review.mdchecks out Khan/actions at a pinned tag in itspre-agent-stepsto fetch the deterministic lib the prompt invokes at runtime. The file's own comment calls thatref:"the single version surface for prompt + code", but nothing updated it during a release: changesets bumpspackage.jsonand changelogs, not prose in a markdown file, so every tag since review-v1.2.2 (v1.3.0, v1.3.1, v1.4.0) shipped with the ref still readingreview-v1.2.2.The skew is not cosmetic: the v1.4.0 prompt invokes
lib/provenance.ts, which does not exist in a v1.2.2 checkout, so an un-overridden consumer gets runtime failures or silently missing gates. It also mis-stamps attribution, since the postedpr-reviewer:versionmarker reads the version from the pinned checkout'spackage.json. (This is the "operational floor" row from the round-two plan, re-confirmed on the review-v1.4.0 tag on 2026-07-09.)Fix: automation, not vigilance
workflows/(release tags are named after the directory, matchingpublishWorkflow) and rewrites every<name>-v<semver>literal in that workflow's markdown files (for review, today, only the checkoutref:line) to that workflow's package version. CHANGELOG.md is skipped (historic versions live there on purpose); a workflow with no literals is a no-op.pnpm run version-packages(changeset versionfollowed by the sync) instead of the defaultchangeset version, so the ref bump lands in the same Version Packages commit that gets tagged. If a Version Packages PR does not bump any workflow package, the sync is a no-op.reviewpackage version. Runs with the existingpnpm run test --runstep in node-ci.review-v1.4.0so the invariant holds on main now; the next release rewrites it automatically.review-vliterals found no other embeds outside changelogs and test fixtures).Changeset included (patch bump for
review; release plumbing and comments only).Verification
pnpm run version-packagesagainst this PR's real changeset (re-run after the generic rewrite):changeset versionbumpedreviewto 1.4.1 and the sync rewrote the ref toreview-v1.4.1in the same working state the changesets action commits (then reset).review-v1.2.2, the backstop test fails as intended.vitestsuite,eslint, andtscall green on the real tree.Once a release ships with the sync in place, webapp's hand-pinned override (its imported review.md carries a "the tag's own ref line lags the release" comment and hand-bumps the ref on every re-import) can be dropped on its next re-import.
cc @jeresig
Human steps (non-review)
review-v1.4.1and the taggedreview.mdcarriesref: review-v1.4.1; the ref bump landed in the same Version Packages commit that was tagged.review-v1.4.1and drops the hand-pinnedref:override comment. Enable the automatic AI PR reviewer on this repo #241 (self-hosted install) was bumped toreview-v1.4.1the same way.