From c36cb4c54cf0951191543519e9b9c953a26b1fa5 Mon Sep 17 00:00:00 2001 From: "MK (fengmk2)" Date: Tue, 17 Nov 2026 13:05:08 +0800 Subject: [PATCH] docs(skill): refine release-manager guidance from the v1.7.0 release - Check each changelog claim against its source, and leave out design context that users do not observe. - Write the upstream upgrade entry as a table, with each new version linked to its upstream release notes. - Allow a measured benchmark table from the PR's report, and keep tables in list items tight. - Smoke-test triage: reopen a PR that missed its pull_request event, compare install logs for no-lockfile drift, check new type errors against the official TypeScript release, use CI hashes for print-config baselines, retry empty carried commits after migrate, and read CI step timings from logs for performance estimates. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/release-manager/SKILL.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/.claude/skills/release-manager/SKILL.md b/.claude/skills/release-manager/SKILL.md index 5948c693bf..8c2fc7d084 100644 --- a/.claude/skills/release-manager/SKILL.md +++ b/.claude/skills/release-manager/SKILL.md @@ -167,10 +167,11 @@ Merging this PR will trigger the release workflow. - `feat(docs)` goes in Docs when the user-facing surface is the docs site. - **Docs means the published docs site, not contributor files.** A `docs` commit that changes an RFC, `AGENTS.md`, the repo map, or a skill under `.claude/` belongs in Chore: a vite-plus user never reads those. Docs should hold only entries a reader could go and look at on the site or in the README. - **Describe behaviour, not resolution logic.** An entry states what a user now observes. Rules the implementation follows internally (target-selection signals, config precedence, detection order) belong in the RFC or the PR, not the changelog. If an entry needs a nested list to explain how a decision is reached, cut it down to the outcome. +- **Check each claim against its source.** For every number, comparison, or emphasis, confirm that the PR body, RFC, or report states it with the same scope, and add no conclusion of your own (for example, a statement about real apps derived from a synthetic benchmark). Say what a measurement compared. Leave out design-document context that does not describe a change users observe, such as an RFC's list of things that stay unchanged or a comparison of package counts. - **A breaking change needs its migration path.** State what existing installs or projects do by default, then how to move to the new behaviour deliberately, then what that costs. Link the guide rather than restating it, and say plainly when doing nothing is a valid choice. - There is no separate Highlights section. Lead Features with up to 5 new capabilities a vite-plus user will notice, plus security fixes from upstream dependency upgrades, then the remaining features; the upstream upgrade entry stays last. Bug fixes go in Fixes & Enhancements even when they are prominent. A security fix in vite-plus's own code is a fix: put it first in Fixes & Enhancements with a `Security:` label, even when the same PR also adds behavior. Skip developer-tooling-only conveniences. - Entry format: `Description ([#N](https://github.com/voidzero-dev/vite-plus/pull/N)), by @author`. Describe the user-visible behavior, not the implementation. Group supporting implementation PRs under the user-visible change they enable instead of giving them separate entries, and fold a new feature's sub-mode (such as its `--watch` flag) into the feature's entry. In Refactor and Chore, keep one contributor's related refactors together in their own entry, and give a notable maintenance change (such as a security-release runtime bump) its own entry. Never include defensive edge cases or internal mechanics unless users need them to use or understand the feature; use concrete behavior instead of internal UI taxonomy that needs extra context. For a fix to an intermittent failure, say that it was rare and when it happened, so the entry does not read as if it always failed. When a PR carries over a superseded PR from another author (its body says so, or `gh pr view N --json commits` lists their commits), credit both authors. Credit only substantive commits: a `Merge branch 'main'` commit on a bot or contributor PR does not make its author a co-author. Check `gh pr view N --json commits` for every PR, not only bot or carried-over PRs, and credit other authors whose commits change code (fixes, behavior, or dependency changes); test-, snapshot-, or doc-only touch-ups do not earn credit. -- **Upstream dependency upgrade PRs** (`feat(deps): upgrade upstream dependencies`): consolidate all of them into one Features entry with net oldest-to-latest version changes (e.g. `vite 8.0.16 -> 8.1.2`), listing every PR number. Check the upgraded range for security fixes (search the upstream changelog for CVE/GHSA); if present, add a dedicated security entry quoting severity and linking the advisory. Cite only published advisories: a draft advisory that maintainer access lets you see is still embargoed, so keep it and its fix's security framing out of the notes and the announcement. When oxfmt or oxlint changed version, add one clause telling users the new versions can flag code that passed before, so they should run `vp check --fix --continue-on-error` after upgrading if their CI runs `vp check` (without `--continue-on-error`, `vp check --fix` skips its final format pass when unfixable lint or type errors remain); in ecosystem testing this is reliably the largest single class of post-upgrade CI failures. Put this entry last in Features as a parent bullet carrying the PR links and credits, with one sub-item per upgraded tool and one per user-facing consequence (new formatting or lint behavior, migration changes, compatibility notes); a single long line is hard to read. +- **Upstream dependency upgrade PRs** (`feat(deps): upgrade upstream dependencies`): consolidate all of them into one Features entry with net oldest-to-latest version changes (e.g. `vite 8.0.16 -> 8.1.2`), listing every PR number. Check the upgraded range for security fixes (search the upstream changelog for CVE/GHSA); if present, add a dedicated security entry quoting severity and linking the advisory. Cite only published advisories: a draft advisory that maintainer access lets you see is still embargoed, so keep it and its fix's security framing out of the notes and the announcement. When oxfmt or oxlint changed version, add one clause telling users the new versions can flag code that passed before, so they should run `vp check --fix --continue-on-error` after upgrading if their CI runs `vp check` (without `--continue-on-error`, `vp check --fix` skips its final format pass when unfixable lint or type errors remain); in ecosystem testing this is reliably the largest single class of post-upgrade CI failures. Put this entry last in Features as a parent bullet carrying the PR links and credits, with a nested table directly under it: columns `Tool`, `Version`, and `What changes for you`, one row per upgraded tool. Write the version as the old version, an arrow, and the new version linked to its upstream release notes, so readers can open the details. Keep each row to one short phrase about the change that matters most to users. Put the follow-up action (the `vp check --fix --continue-on-error` advice, migration or compatibility notes) as sub-items after the table. Long per-tool sentences are hard to read, and the linked release notes and the Bundled Versions table carry the details. - **vite-plus security advisories**: list the repository advisories (`gh api repos/voidzero-dev/vite-plus/security-advisories --jq '.[] | [.ghsa_id, .state, .summary] | @tsv'`) and match each draft advisory to its fix PR in the release. While the advisory is a draft, describe that PR by its behavior only: no GHSA ID, `Security:` label, or attack wording in the release PR, the release notes, or the announcement. Keep the credit for the reporter when they co-authored the fix, because the commit trailer already shows it. When the advisory is published (often soon after the npm publication), add the severity and the advisory link to the entry in the release notes and a `:lock:` line to the announcement. Link the repository advisory page (`https://github.com/voidzero-dev/vite-plus/security/advisories/GHSA-...`) until the global advisory database lists it. - **vite-task bumps** (`bump vite-task to `): expand the full rev range (compare `Cargo.toml` at `v` vs the release branch), run `git log ..` in the local vite-task checkout, and read vite-task's `CHANGELOG.md` at the new commit for wording. Promote user-visible upstream changes into Features / Fixes with `[vite-task#N](https://github.com/voidzero-dev/vite-task/pull/N)` links, crediting the upstream PR author (`gh pr view N --repo voidzero-dev/vite-task --json author`). Cross-repo link format is `[vite-task#N]` / `[vite#N]`, not `[owner/repo#N]`. - New Contributors: copy from `generate-notes`, exclude bots (`renovate[bot]`, `voidzero-guard[bot]`, `github-actions[bot]`), list as inline `@mentions`. `generate-notes` only covers vite-plus, so also add first-time contributors from the expanded vite-task range: an author is new when `gh api -X GET search/issues -f q='repo:voidzero-dev/vite-task is:pr is:merged author: merged:<' -q .total_count` is 0. List them with the others, without a repository label, in the release notes and the Discord thanks line. @@ -193,11 +194,11 @@ vite and rolldown are built from pinned commits, so link the commit. The npm-ins - No em dashes or en dashes anywhere in the title or body. Use commas, colons, or parentheses. - Keep the PR title plain (`release: vX.Y.Z`) and the GitHub release title plain (`vite-plus vX.Y.Z`); the theme goes in the opening sentence. Lead the opening theme with the most important user-visible behavior. Avoid vague benefit-only wording that the body must explain. When several tools were upgraded, do not name a few of them in the opening sentence; the upgrade entry covers them. -- Say what a feature does. Do not compare it to the tool it replaces, and do not say it works "without" a dependency it never needed. +- Say what a feature does. Do not compare it to the tool it replaces, and do not say it works "without" a dependency it never needed. A measured comparison from the PR's benchmark report is the exception: put it in a nested table under the entry, copy the values from the report, and name the hardware, the run counts, and the compared versions. - When naming a package version in prose or a heading, use one inline literal, `package@version`. Keep separate version columns in tables. - Link unfamiliar technical abbreviations to the relevant documentation section; keep the short abbreviation as the link text. - The Upgrade section is a `vp upgrade` code block. -- Put commands that readers run, such as install commands, in a code block indented under the list item, not in inline code. Start the fence on the line directly after the item text: a blank line inside one item makes the whole list loose, and GitHub then adds paragraph spacing between every item of that section. Check with `gh api markdown` (mode `gfm`) that no `
  • ` opens a `

    `. +- Put commands that readers run, such as install commands, in a code block indented under the list item, not in inline code. Start the fence on the line directly after the item text: a blank line inside one item makes the whole list loose, and GitHub then adds paragraph spacing between every item of that section. Check with `gh api markdown` (mode `gfm`) that no `

  • ` opens a `

    `. The same applies to a table inside a list item: put its header row on the line directly after the item text, with no blank line. - Apply via a temp file, never a heredoc (heredoc quoting can escape backticks inside the table and break rendering): ```bash @@ -327,7 +328,7 @@ Across the full catalog most failures are not regressions, and reporting them as - **Stale pnpm metadata from an earlier sweep.** If migrate's install fails with `ERR_PNPM_NO_MATCHING_VERSION` for a version that npm serves, and pnpm names an older "latest release", pnpm read metadata that it cached under the bridge registry during an earlier sweep. Delete the bridge-keyed metadata older than a day (on macOS: `find ~/Library/Caches/pnpm/v*/metadata* -path '*registry-bridge.viteplus.dev*' -type f -mtime +0 -delete`) and rerun the fork. -- **Forks that report no checks.** Before you count a fork as passing, check its last workflow run (`gh api 'repos/vite-plus-ecosystem-ci//actions/runs?per_page=1'`). GitHub can disable Actions on a fork while the settings API still reports `enabled: true`; `gh workflow run` then fails with `Actions has been disabled for this repository`. Run the fork's main CI commands locally against the preview and report that evidence separately. +- **Forks that report no checks.** Before you count a fork as passing, check its last workflow run (`gh api 'repos/vite-plus-ecosystem-ci//actions/runs?per_page=1'`). GitHub can disable Actions on a fork while the settings API still reports `enabled: true`; `gh workflow run` then fails with `Actions has been disabled for this repository`. Run the fork's main CI commands locally against the preview and report that evidence separately. A fork with working Actions can also miss one PR event: when a sync pushes to the tracked branch seconds before the PR opens, GitHub can start no `pull_request` run. If the fork's other runs are recent, close and reopen the draft PR to send a new event before you classify the fork as Actions-disabled. - **Preview-build artifacts.** These are caused by the `0.0.0-commit.` version string itself and cannot happen for a real npm release, so they are never blockers. The recurring ones: pnpm `ERR_PNPM_TRUST_DOWNGRADE` ("possible package takeover"), npm `ETARGET` from a `before`/min-release-age policy, bun `minimum release age`, `ERR_PNPM_INVALID_PEER_DEPENDENCY_SPECIFICATION` when a project declares `vite` as a peer (migrate writes the `npm:@voidzero-dev/vite-plus-core@...` alias there), `ERR_PNPM_TARBALL_URL_MISMATCH` or a failed supply-chain policy check against the bridge tarball URLs, Docker builds whose context does not carry the bridge `.npmrc`, checks that compare the generated Vite+ block in `AGENTS.md` (preview builds compile the PR's docs preview origin into CLI output, while release builds use `https://viteplus.dev`), project scripts that query `vite@*` or `vite-plus@*` and find nothing (the prerelease does not match `*`), and npm 10 failing with `Unable to resolve reference $vite-plus` on a nested `overrides` entry. Confirm the last two by swapping the commit version for a real release in a scratch copy. - **Pre-existing failures.** Prove it rather than asserting it, with whichever control is cheaper: install the previous release into an isolated home and re-run the same command, or check whether the fork's base branch CI already fails. The isolated-home control is the highest-value technique in this step, since it converts a scary-looking failure into a one-line fact: @@ -357,13 +358,16 @@ Across the full catalog most failures are not regressions, and reporting them as Report that subset separately; "2 of the 7 forks on the previous release pass, the other 5 fail on fork infrastructure" is a far stronger statement than a headline pass rate over the whole catalog. - **Project-side and infra failures.** Dependency conflicts between the project's own packages, missing fork secrets, third-party GitHub Apps not installed on the fork, network timeouts. Retry once before classifying anything as a network failure; they pass on retry. Two recurring shapes worth naming: a package that imports a dependency it never declared and only ever resolved through hoisting (`Cannot find package 'oxfmt'`) breaks as soon as the harness regenerates the lockfile; and a project whose own dependency has no `main`/`module`/`exports` cannot load its config under any vite-plus version. A full-catalog sweep can use up the org's macOS runner capacity: macOS jobs then wait about an hour and end as cancelled, with no runner name and no steps. Rerun them after the load drops. A dependency that patches or wraps the oxlint binary can reject a new oxlint version; bump it on the test branch, and classify the diagnostics that its new version adds as third-party drift. -- **Dependency drift during migration.** Regenerating a lockfile can move unrelated floating or nightly dependencies to incompatible versions. Compare with the base lockfile before blaming the candidate. On the test branch, retain the original versions and their dependency graph, then verify a frozen install and rerun the failing command. -- **Custom quality checks.** Check that project wrappers still load their plugins and recognize migrated test imports. Preserve existing lint diagnostic coverage when repairing migration issues; a smaller baseline can mean that checks stopped running. +- **Dependency drift during migration.** Regenerating a lockfile can move unrelated floating or nightly dependencies to incompatible versions. Compare with the base lockfile before blaming the candidate. On the test branch, retain the original versions and their dependency graph, then verify a frozen install and rerun the failing command. A project that commits no lockfile, or a CI that installs with `--no-lockfile`, resolves dependencies afresh in each run, so a new upstream release between the control run and the candidate run can fail a test. Compare the `+ ` lines of the two install logs, and confirm a suspect release by swapping its version locally. +- **New compiler diagnostics.** When the bundled type checker targets a newer TypeScript version, check a new type error against the official compiler before blaming the backend: run `tsc --noEmit -p ` from the old and the new `typescript` release (for example through `npx -p typescript@`) in the fork, and compare the same file. A library change, such as a new DOM property, also shows in the `lib.*.d.ts` files that each tool ships. +- **Custom quality checks.** Check that project wrappers still load their plugins and recognize migrated test imports. Preserve existing lint diagnostic coverage when repairing migration issues; a smaller baseline can mean that checks stopped running. Compare a rebuilt baseline per rule before you commit it. A checked-in baseline that hashes `oxlint --print-config` output can depend on the checkout path when a shared config computes absolute plugin paths; record the hash that CI reports, not a local one. - **Release-age gates on fresh dependencies.** A project's `minimumReleaseAge` can reject packages that Vite+ itself pins and that were published shortly before the release. That is the project's policy, not a vite-plus bug: add the package to `minimumReleaseAgeExclude` on the test branch, and do not propose extending migrate's exemption list. Real installs of the release hit the same gate until those packages age past the project's window. - **Harness artifacts.** Failures your own test setup caused, such as a lockfile the harness deleted and the install never regenerated. Fix these and re-run rather than reporting them. Report the tally by cause, not just pass/fail, and state plainly which failures you controlled for and which you classified from the error text alone. Only a failure that reproduces on the candidate but not on the previous release is a regression. +To estimate a performance change from fork CI, compare the same step between the previous cycle's PR and the current one. Read durations from the log timestamps (the jobs API rounds steps to whole seconds), resolve wrapper scripts to the commands they run, and keep only steps that passed in both runs and took at least 5 seconds. Runner and cache differences make this indicative only; point to the controlled benchmark for exact numbers. + Before filing an upstream issue for a finding, search every repository that could own it, including closed issues and open PRs. For a type-aware oxlint diagnostic that means both `oxc-project/oxc` and `oxc-project/tsgolint`. When repairing timing-sensitive smoke tests, keep their assertions and make readiness or timing deterministic. Use a negative control when changing how a test observes behavior: temporarily remove or break that behavior, confirm the test fails, and restore it before committing. @@ -372,7 +376,7 @@ Two long-run mechanics worth knowing: `vp migrate` installs Vite+ git hooks in t Two fork-CI blockers are worth fixing rather than reporting, both on the **test branch only** so the tracked branch stays clean against upstream. A fork whose workflows never trigger on `pull_request` reports "no checks" and proves nothing: add a minimal workflow that runs `vp run build` through whatever setup the project already uses. A fork whose workflows target third-party runners (self-hosted labels such as `blacksmith-*`) queues every job forever, because those labels only resolve for the upstream org: map them to GitHub-hosted equivalents, replacing the longest label first so an `-arm` suffix is not left half-rewritten. Runner-specific _actions_ need more than a label swap and are usually not worth fixing. The same applies to `depot-*` and `namespace-profile-*` labels. GitHub-hosted runners are smaller than most of these, so heavy suites can start timing out after the swap; classify those timeouts as fork infrastructure. -Closing a cycle's PRs with `--delete-branch` removes their test branches, but each closed PR's commits stay reachable at `refs/pull//head`. Find the previous cycle's PR per repository (`gh pr list --repo vite-plus-ecosystem-ci/ --state all`); an org-wide `gh search` stops at 100 results and silently misses forks. Before a new sweep, list the non-upgrade commits on the previous cycle's PRs (supply-chain exemptions, runner-label maps, added workflows), fetch them, and cherry-pick them onto the new test branches. Re-apply by hand when upstream drift makes a cherry-pick conflict. Commits made after the upgrade commit (formatting of migrate-written files, regenerated lockfiles, restored dependencies) only apply after migrating: retry them after the new upgrade commit, take the new lockfile when only lockfiles conflict, and drop a formatting commit that would add migrate-generated `package.json` or workspace keys before migrate runs. Redo, instead of cherry-picking, each commit whose content depends on the build under test: formatting, lockfile refreshes, oxlint baselines, pins to bundled tool versions, and a refreshed Vite+ block in `AGENTS.md`, which carries the previous preview's docs origin. Drop carried-over fixes that upstream made obsolete (for example a rule disable that upstream replaced with inline comments), and redo pins in restored dependencies with the currently bundled versions instead of carrying the old ones forward. When a re-applied commit changes `package.json` but its lockfile part conflicts, reinstall after re-applying and commit the refreshed lockfile; otherwise the frozen install in fork CI fails on the mismatch. +Closing a cycle's PRs with `--delete-branch` removes their test branches, but each closed PR's commits stay reachable at `refs/pull//head`. Find the previous cycle's PR per repository (`gh pr list --repo vite-plus-ecosystem-ci/ --state all`); an org-wide `gh search` stops at 100 results and silently misses forks. Before a new sweep, list the non-upgrade commits on the previous cycle's PRs (supply-chain exemptions, runner-label maps, added workflows), fetch them, and cherry-pick them onto the new test branches. Re-apply by hand when upstream drift makes a cherry-pick conflict. A carried commit that is empty before migrating can still be needed after it, when it reverts migrate output (for example, it keeps `vitest` imports in a standalone template): retry empty commits after the new upgrade commit too. Commits made after the upgrade commit (formatting of migrate-written files, regenerated lockfiles, restored dependencies) only apply after migrating: retry them after the new upgrade commit, take the new lockfile when only lockfiles conflict, and drop a formatting commit that would add migrate-generated `package.json` or workspace keys before migrate runs. Redo, instead of cherry-picking, each commit whose content depends on the build under test: formatting, lockfile refreshes, oxlint baselines, pins to bundled tool versions, and a refreshed Vite+ block in `AGENTS.md`, which carries the previous preview's docs origin. Drop carried-over fixes that upstream made obsolete (for example a rule disable that upstream replaced with inline comments), and redo pins in restored dependencies with the currently bundled versions instead of carrying the old ones forward. When a re-applied commit changes `package.json` but its lockfile part conflicts, reinstall after re-applying and commit the refreshed lockfile; otherwise the frozen install in fork CI fails on the mismatch. ## 5. Release-branch CI