fix(tools): add preflight checks and rollback to release script by marcoscaceres · Pull Request #5235 · speced/respec

marcoscaceres · 2026-04-30T06:38:29Z

The release script could fail mid-release (after committing the version bump and tag) due to missing external dependencies, leaving the repo in a state requiring manual cleanup.

Adds three improvements:

Preflight checks run before any mutations — verifying Java (for vnu), Puppeteer Chrome (for respec2html), and that gh-pages resolves unambiguously. Fails fast with actionable fix instructions.

Rollback on failure — saves the pre-release HEAD sha and restores it if anything fails before the push. Deletes the local tag, resets main and gh-pages to their pre-release state. After push (point of no return), if only npm publish fails, it tells you to run npm publish manually instead of rolling back git.

Interactive npm publish — switches from exec() to spawn() with inherited stdio so the npm OTP browser auth flow works.

Copilot

Pull request overview

This PR hardens the tools/release.cjs release workflow by adding upfront dependency checks, adding a local rollback path on failures before pushing, and making npm publish interactive to support OTP/browser auth.

Changes:

Add preflight checks for Java (vnu), Puppeteer-managed Chrome (respec2html), and gh-pages branch resolution.
Add rollback logic to restore pre-release main/gh-pages state and delete the local tag when failures occur before pushing.
Switch npm publish execution from exec() to spawn() with inherited stdio for interactive auth.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

marcoscaceres · 2026-04-30T08:39:56Z

@copilot Can you confirm all your feedback has been addressed? Can you fix anything that was not addressed?

Copilot · 2026-04-30T08:41:15Z

@copilot Can you confirm all your feedback has been addressed? Can you fix anything that was not addressed?

All four items from the automated review were addressed in commit 6c29f2f:

origin/gh-pages existence — preflight now explicitly checks remotes.some(r => r.trim() === "origin/gh-pages") and fails with a git fetch origin gh-pages hint if missing.
origin-specific check — covered by the same fix above.
remote update before preflight() — git remote update (with its loading indicator) now runs before preflight() so the gh-pages ref check sees fresh data.
pushed = true after first push — moved to immediately after git push origin main so partial push failures don't trigger an incorrect local rollback.

Nothing left to address.

marcoscaceres · 2026-05-04T13:05:47Z

@copilot Can you confirm all your feedback has been addressed? Can you fix anything that was not addressed?

Copilot · 2026-05-04T13:08:49Z

@copilot Can you confirm all your feedback has been addressed? Can you fix anything that was not addressed?

All original review feedback is addressed in the current code:

origin/gh-pages existence — preflight explicitly checks remotes.some(r => r.trim() === "origin/gh-pages") (line 386) and errors with a git fetch origin gh-pages hint if missing.
origin-specific check — covered by the same fix.
git remote update before preflight() — remote update runs at lines 502–504, before preflight() at line 506.
pushed = true placement — it's set at line 574, immediately after git push origin main (the first push), not after all three. This is the correct point-of-no-return: if gh-pages or tags push fails after main is already pushed, the catch block skips local rollback and shows the manual-fix message instead.

Nothing further needs to be changed.

Closes #5234

- Check origin/gh-pages exists specifically, not just count remotes - Move remote update before preflight so refs are current - Set pushed=true after first push (point of no return)

The W3C CDN syncs from GitHub Releases, not tags. Without this step, new versions don't reach specs until someone manually creates a release. Adds gh CLI to preflight checks.

Previously pushed=true was set after only "git push origin main". If "git push origin gh-pages" or "git push --tags" failed, the error handler would incorrectly claim "Git push succeeded." Also fix prefer-template lint error.

sidvishnoi

Mostly recommending to use git switch instead of checkout.

sidvishnoi · 2026-05-08T09:32:57Z

+  try {
+    const currentBranch = await getCurrentBranch();
+    if (currentBranch !== "main") {
+      await git("checkout main");


Suggested change

await git("checkout main");

await git("switch main");

sidvishnoi · 2026-05-08T09:33:37Z

+  }
+  if (ghPagesHead) {
+    try {
+      await git("checkout gh-pages");


Suggested change

await git("checkout gh-pages");

await git("switch gh-pages");

sidvishnoi · 2026-05-08T09:33:48Z

+      console.log(
+        colors.yellow(`  Reset gh-pages to ${ghPagesHead.slice(0, 8)}`)
+      );
+      await git("checkout main");


Suggested change

await git("checkout main");

await git("switch main");

sidvishnoi · 2026-05-08T09:34:21Z

+      console.log(
+        colors.yellow(`  Reset gh-pages to ${ghPagesHead.slice(0, 8)}`)
+      );
+      await git("checkout main");


Should probably do this in finally?

sidvishnoi · 2026-05-08T09:34:32Z

+  try {
+    const currentBranch = await getCurrentBranch();
+    if (initialBranch !== currentBranch) {
+      await git(`checkout ${initialBranch}`);


Suggested change

await git(`checkout ${initialBranch}`);

await git(`switch ${initialBranch}`);

marcoscaceres · 2026-05-08T10:34:33Z

@copilot can you evaluate and merge in @sidvishnoi's suggested changes?

Agent-Logs-Url: https://github.com/speced/respec/sessions/0508d20f-e1d6-48cc-944a-844e47692548 Co-authored-by: marcoscaceres <870154+marcoscaceres@users.noreply.github.com>

Copilot · 2026-05-08T10:36:47Z

@copilot can you evaluate and merge in @sidvishnoi's suggested changes?

Done in commit 1c16849. Applied all four of @sidvishnoi's suggestions: replaced git checkout with git switch at the four locations in the rollback function (lines 456, 477, 482, 490), and moved the switch main after the gh-pages reset into a finally block so it always runs even if the reset fails.

marcoscaceres requested a review from Copilot April 30, 2026 06:50

Copilot started reviewing on behalf of marcoscaceres April 30, 2026 06:51 View session

Copilot AI reviewed Apr 30, 2026

View reviewed changes

Comment thread tools/release.cjs

Comment thread tools/release.cjs

Comment thread tools/release.cjs Outdated

Comment thread tools/release.cjs

Copilot started work on behalf of marcoscaceres April 30, 2026 08:40 View session

Copilot finished work on behalf of marcoscaceres April 30, 2026 08:42

Copilot started work on behalf of marcoscaceres May 4, 2026 13:05 View session

Copilot finished work on behalf of marcoscaceres May 4, 2026 13:09

marcoscaceres added 4 commits May 5, 2026 20:01

fix(tools): add preflight checks and rollback to release script

8ab2bec

Closes #5234

fix: address Copilot review feedback

61085f2

- Check origin/gh-pages exists specifically, not just count remotes - Move remote update before preflight so refs are current - Set pushed=true after first push (point of no return)

feat(tools): create GitHub Release after npm publish

39fa592

The W3C CDN syncs from GitHub Releases, not tags. Without this step, new versions don't reach specs until someone manually creates a release. Adds gh CLI to preflight checks.

fix: set pushed flag after all 3 git push commands succeed

29b0746

Previously pushed=true was set after only "git push origin main". If "git push origin gh-pages" or "git push --tags" failed, the error handler would incorrectly claim "Git push succeeded." Also fix prefer-template lint error.

marcoscaceres force-pushed the fix/release-script-preflight branch from 727e871 to 29b0746 Compare May 5, 2026 10:01

marcoscaceres requested a review from sidvishnoi May 8, 2026 08:20

Merge branch 'main' into fix/release-script-preflight

0a7bf1f

sidvishnoi approved these changes May 8, 2026

View reviewed changes

Copilot started work on behalf of marcoscaceres May 8, 2026 10:34 View session

refactor(tools): use git switch instead of checkout in rollback function

1c16849

Agent-Logs-Url: https://github.com/speced/respec/sessions/0508d20f-e1d6-48cc-944a-844e47692548 Co-authored-by: marcoscaceres <870154+marcoscaceres@users.noreply.github.com>

Copilot finished work on behalf of marcoscaceres May 8, 2026 10:37

marcoscaceres merged commit 593d96e into main May 8, 2026
9 checks passed

marcoscaceres deleted the fix/release-script-preflight branch May 8, 2026 10:39

	await git("checkout gh-pages");
	await git("switch gh-pages");

	await git(`checkout ${initialBranch}`);
	await git(`switch ${initialBranch}`);

Uh oh!

Conversation

marcoscaceres commented Apr 30, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marcoscaceres commented Apr 30, 2026

Uh oh!

Copilot AI commented Apr 30, 2026

Uh oh!

marcoscaceres commented May 4, 2026

Uh oh!

Copilot AI commented May 4, 2026

Uh oh!

sidvishnoi left a comment

Choose a reason for hiding this comment

Uh oh!

sidvishnoi May 8, 2026

Choose a reason for hiding this comment

Uh oh!

sidvishnoi May 8, 2026

Choose a reason for hiding this comment

Uh oh!

sidvishnoi May 8, 2026

Choose a reason for hiding this comment

Uh oh!

sidvishnoi May 8, 2026

Choose a reason for hiding this comment

Uh oh!

sidvishnoi May 8, 2026

Choose a reason for hiding this comment

Uh oh!

marcoscaceres commented May 8, 2026

Uh oh!

Copilot AI commented May 8, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants