Dev

Development skills

• Rolling Playwright dependency roll.md
• Preparing Release release.md

How to prepare a release

A release is a chore: mark v<next-patch> commit whose PR body is the release notes. Example: https://github.com/microsoft/playwright-cli/pull/367.

Steps

1. Bump the patch version in package.json (e.g. 0.1.7 → 0.1.8), then npm install to sync package-lock.json. This is the entry point — everything else (branch name, PR title, release notes filename) keys off the new version.

2. Find the baseline. The previous release is the last chore: mark v... commit on main. Read the Playwright version pinned at that commit — that's the baseline for the diff.

   git log --oneline | grep "mark v" | head -1
   git show <sha>:package.json | grep '"playwright"'

3. Figure out the playwright commit window. Convert the baseline's alpha timestamp to a UTC date, and use the new alpha's date as the upper bound. Alphas are either 1.X.0-alpha-<ms-epoch> or 1.X.0-alpha-<YYYY-MM-DD>.

   date -u -d @<seconds> '+%Y-%m-%d %H:%M:%S UTC'   # for ms-epoch, divide by 1000 first

4. List Playwright commits in the window. Run from ~/code/playwright (a local Playwright checkout). --after / --before work on any ref regardless of what origin/main currently points at; --since / --until can silently return empty if the branch is behind.

   cd ~/code/playwright && git log --after='<baseline-date>' --before='<new-date>' --pretty=format:'%h %ci %s'

5. Filter to CLI-relevant commits. Keep anything touching the CLI surface or its runtime; drop internal/unrelated churn.

• Keep: src/tools/cli-client/**, src/tools/cli-daemon/**, src/tools/mcp/**, remote/playwrightConnection, CDP-attach paths, tracing/video APIs the CLI exposes, and anything with a fix(cli) / feat(cli) / fix(mcp) / feat(mcp) prefix.
• Drop: test-runner rolls, firefox/chromium/webkit version bumps, docs-only, test infra, unrelated refactors.
• Use git show --stat <sha> to sanity-check whether a commit's files touch the CLI.

6. Pull issue context for each kept PR. The PR's linked issue often has better user-facing wording than the PR/commit title.

   gh pr view <pr> --repo microsoft/playwright --json title,body,closingIssuesReferences
   gh issue view <issue> --repo microsoft/playwright-cli --json title,body,state

7. Write the release notes to RELEASE_NOTES_v<version>.md. Use this exact shape — no top-level `#` header, the PR title is the heading:

   ## Highlights

   - **<issue wording, not commit wording>** ([#<issue>](https://github.com/microsoft/playwright-cli/issues/<issue>)) — one sentence on the user-facing effect. ([microsoft/playwright#<pr>](https://github.com/microsoft/playwright/pull/<pr>))

   ## Fixes

   - `<commit subject>` — what changed and why it matters. ([#<pr>](https://github.com/microsoft/playwright/pull/<pr>))

   ## Upgrading

npm install -g @playwright/cli@<version>

Wording rules:

• Highlights lead with the user-reported problem from the linked issue, not the commit subject. Drop internal terms (cdpPort, tombstones) from highlight bullets.
• Only list things that change user-visible behavior. Skip internal cleanups unless they have a user-facing effect.
• Reference both the playwright-cli issue (if any) and the microsoft/playwright PR.

8. Commit, push, open PR. The PR body is the contents of the release notes file (no # header, no filename).

   git checkout -b mark-v<version>
   git add package.json package-lock.json
   git commit -m "chore: mark v<version>"
   git push -u origin mark-v<version>
   gh pr create --repo microsoft/playwright-cli \
     --head pavelfeldman:mark-v<version> \
     --base main \
     --title "chore: mark v<version>" \
     --body "$(cat RELEASE_NOTES_v<version>.md)"

Pitfalls

• Don't use `--since` / `--until` when diffing Playwright — if origin/main in the local checkout is behind, they return empty. --after / --before against the local ref work.
• Don't include a `# playwright-cli vX.Y.Z` header in the PR body — GitHub already renders the PR title.
• Don't paraphrase the commit subject as the highlight. A user who filed an issue described the pain; reuse their framing.
• Don't include test-runner / browser-version-roll commits in release notes — they're noise for CLI users.

How to roll Playwright dependency

Steps

1. Obtain latest Playwright version npm info playwright@next version

2. Update Playwright packages in package.json:

• Update playwright (dependency) and @playwright/test (devDependency) to the target version.
• Run npm install to update package-lock.json.

3. Run the update script to sync skills and README:

   node scripts/update.js

This script:

• Runs node playwright-cli.js install --skills to regenerate skills from the new Playwright version.
• Copies the generated skills from .claude/skills/playwright-cli/ into skills/playwright-cli/.
• Cleans up the generated .claude/skills/ directory.

3. Update README.md with relevant changes from the updated skill at skills/playwright-cli/SKILL.md. Compare the skill file with the README and update any sections that are out of date (commands, flags, default behaviors, examples).

4. Verify the CLI works:

   node playwright-cli.js --help

5. Test the CLI:

   npm run test

5. Create a branch and commit:

• Branch name: roll_<version> (e.g. roll_214)
• Commit message: chore: roll Playwright to <version>
• do not add Co-Authored-By

Key files