From 4d909c3821ce6a4bed7f6ac5a01e94d8116ba0cf Mon Sep 17 00:00:00 2001 From: Yury Semikhatsky Date: Fri, 12 Jun 2026 10:57:14 -0700 Subject: [PATCH 1/3] chore: extract common skill conventions into CLAUDE.md Move the shared commit/PR conventions and JS-mirroring notes out of the roll skill into a top-level CLAUDE.md, aligned with the upstream playwright CLAUDE.md. --- .claude/skills/playwright-roll/SKILL.md | 36 ++------------------- CLAUDE.md | 43 +++++++++++++++++++++++++ 2 files changed, 45 insertions(+), 34 deletions(-) create mode 100644 CLAUDE.md diff --git a/.claude/skills/playwright-roll/SKILL.md b/.claude/skills/playwright-roll/SKILL.md index 323a13926..6cad183b9 100644 --- a/.claude/skills/playwright-roll/SKILL.md +++ b/.claude/skills/playwright-roll/SKILL.md @@ -53,7 +53,7 @@ Rolling includes: ## Mimicking the JavaScript implementation -The Java client is a port of the JS client in `../playwright/packages/playwright-core/src/client/`. When implementing a new or changed method, always read the corresponding JS file first and mirror its logic: +The Java client is a port of the JS client in `../playwright/packages/playwright-core/src/client/` (see CLAUDE.md). When implementing a new or changed method, always read the corresponding JS file first and mirror its logic: ``` ../playwright/packages/playwright-core/src/client/browserContext.ts @@ -167,36 +167,4 @@ When you've identified a hanging test: ## Commit Convention -Semantic commit messages: `label(scope): description` - -Labels: `fix`, `feat`, `chore`, `docs`, `test`, `devops` - -```bash -git checkout -b fix-39562 -# ... make changes ... -git add -git commit -m "$(cat <<'EOF' -fix(proxy): handle SOCKS proxy authentication - -Fixes: https://github.com/microsoft/playwright-java/issues/39562 -EOF -)" -git push origin fix-39562 -gh pr create --repo microsoft/playwright-java --head username:fix-39562 \ - --title "fix(proxy): handle SOCKS proxy authentication" \ - --body "$(cat <<'EOF' -## Summary -- - -Fixes https://github.com/microsoft/playwright-java/issues/39562 -EOF -)" -``` - -Never add Co-Authored-By agents in commit message. -Never add "Generated with" in commit message. -Branch naming for issue fixes: `fix-` - -## Tips & Tricks -- Project checkouts are in the parent directory (`../`). -- use the "gh" cli to interact with GitHub +Commit and PR conventions live in CLAUDE.md. Use the running notes file as the PR body: list each upstream PR ported, each skipped (with reason), and each verified-already-supported. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..9962ad080 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,43 @@ +# Playwright Java + +The Java client is a port of the JavaScript client in `../playwright/packages/playwright-core/src/client/`. When implementing or changing a method, read the corresponding JS file first and mirror its logic. + +Project checkouts (including the upstream `playwright` repo) live in the parent directory (`../`). Use the `gh` cli to interact with GitHub. + +## Commit Convention + +Semantic commit messages: `label(scope): description` + +Labels: `fix`, `feat`, `chore`, `docs`, `test`, `devops` + +```bash +git checkout -b fix-39562 +# ... make changes ... +git add +git commit -m "$(cat <<'EOF' +fix(proxy): handle SOCKS proxy authentication + +Fixes: https://github.com/microsoft/playwright-java/issues/39562 +EOF +)" +# **Never `git push` without an explicit instruction to push.** +git push origin fix-39562 +gh pr create --repo microsoft/playwright-java --head :fix-39562 \ + --title "fix(proxy): handle SOCKS proxy authentication" \ + --body "$(cat <<'EOF' +## Summary +- + +Fixes https://github.com/microsoft/playwright-java/issues/39562 +EOF +)" +``` + +Never add Co-Authored-By agents in commit message. +Never add "Generated with" in commit message. +Never add test plan to PR description. Keep PR description short — a few bullet points at most. +Branch naming for issue fixes: `fix-`. + +**Never amend commits.** Always create a new commit for follow-up changes, even when iterating on an open PR. Amending rewrites history and forces a force-push, losing the incremental review trail. Only amend if the user explicitly says so. + +**Never `git push` without an explicit instruction to push.** Applies even when a PR is already open for the branch — additional commits are immediately visible to reviewers. Commit locally, report what was committed, and wait. Only push when the user's message contains "push", "upload", "create PR", "ship it", or equivalent. From 4ceb8396b06232595adc85b6be0a4220cc0cefba Mon Sep 17 00:00:00 2001 From: Yury Semikhatsky Date: Fri, 12 Jun 2026 11:02:37 -0700 Subject: [PATCH 2/3] chore: reference skills from CLAUDE.md, drop back-references Add a Skills section to CLAUDE.md linking the roll and release skills, remove the leftover Commit Convention section from the roll skill, and drop the CLAUDE.md back-references from the skills. --- .claude/skills/playwright-roll/SKILL.md | 6 +----- CLAUDE.md | 5 +++++ 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/.claude/skills/playwright-roll/SKILL.md b/.claude/skills/playwright-roll/SKILL.md index 6cad183b9..7a37f386f 100644 --- a/.claude/skills/playwright-roll/SKILL.md +++ b/.claude/skills/playwright-roll/SKILL.md @@ -53,7 +53,7 @@ Rolling includes: ## Mimicking the JavaScript implementation -The Java client is a port of the JS client in `../playwright/packages/playwright-core/src/client/` (see CLAUDE.md). When implementing a new or changed method, always read the corresponding JS file first and mirror its logic: +The Java client is a port of the JS client in `../playwright/packages/playwright-core/src/client/`. When implementing a new or changed method, always read the corresponding JS file first and mirror its logic: ``` ../playwright/packages/playwright-core/src/client/browserContext.ts @@ -164,7 +164,3 @@ When you've identified a hanging test: 1. Run it in isolation: `mvn -f playwright/pom.xml test -Dtest='TestClass#testMethod'`. If it passes alone, it's a parallel-load flake — note it but move on. 2. If it still hangs in isolation, look for a recent fix in the upstream repo for the *same* test name. Use `git log --oneline tests/library/.spec.ts` in `~/playwright`. Upstream fixes for client-side hangs are often small and portable (e.g. `about:blank` → `server.EMPTY_PAGE` from microsoft/playwright#39840 fixed `route-web-socket.spec.ts` arraybuffer hangs — apparently some browser changed the WebSocket origin policy on `about:blank`). 3. When porting an upstream fix, mirror the helper signature change rather than hard-coding workarounds. E.g. if upstream added a `server` parameter to `setupWS`, do the same in Java by injecting `Server server` via the JUnit fixture (`@FixtureTest` already wires up `ServerLifecycle`, so adding `Server server` to the test method signature is enough — no class-level boilerplate). Watch for local-variable shadowing when you add a `Server server` parameter to a method that already has a `WebSocketRoute server` local; rename the local. - -## Commit Convention - -Commit and PR conventions live in CLAUDE.md. Use the running notes file as the PR body: list each upstream PR ported, each skipped (with reason), and each verified-already-supported. diff --git a/CLAUDE.md b/CLAUDE.md index 9962ad080..b9a57c2ed 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,6 +4,11 @@ The Java client is a port of the JavaScript client in `../playwright/packages/pl Project checkouts (including the upstream `playwright` repo) live in the parent directory (`../`). Use the `gh` cli to interact with GitHub. +## Skills + +- **playwright-roll** (`.claude/skills/playwright-roll/SKILL.md`) — roll Playwright Java to a new upstream version: bump the driver, regenerate the API, and port relevant upstream changes. +- **playwright-java-release** (`.claude/skills/playwright-java-release/SKILL.md`) — prepare a release after the rolling PR merges: cut the release branch, mark the Maven version, and draft the GitHub release. + ## Commit Convention Semantic commit messages: `label(scope): description` From 95bbef51bb661717a795f0762019d1a14ad1b652 Mon Sep 17 00:00:00 2001 From: Yury Semikhatsky Date: Fri, 12 Jun 2026 11:02:58 -0700 Subject: [PATCH 3/3] chore: move Skills section to end of CLAUDE.md --- CLAUDE.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b9a57c2ed..1433460ef 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,11 +4,6 @@ The Java client is a port of the JavaScript client in `../playwright/packages/pl Project checkouts (including the upstream `playwright` repo) live in the parent directory (`../`). Use the `gh` cli to interact with GitHub. -## Skills - -- **playwright-roll** (`.claude/skills/playwright-roll/SKILL.md`) — roll Playwright Java to a new upstream version: bump the driver, regenerate the API, and port relevant upstream changes. -- **playwright-java-release** (`.claude/skills/playwright-java-release/SKILL.md`) — prepare a release after the rolling PR merges: cut the release branch, mark the Maven version, and draft the GitHub release. - ## Commit Convention Semantic commit messages: `label(scope): description` @@ -46,3 +41,8 @@ Branch naming for issue fixes: `fix-`. **Never amend commits.** Always create a new commit for follow-up changes, even when iterating on an open PR. Amending rewrites history and forces a force-push, losing the incremental review trail. Only amend if the user explicitly says so. **Never `git push` without an explicit instruction to push.** Applies even when a PR is already open for the branch — additional commits are immediately visible to reviewers. Commit locally, report what was committed, and wait. Only push when the user's message contains "push", "upload", "create PR", "ship it", or equivalent. + +## Skills + +- **playwright-roll** (`.claude/skills/playwright-roll/SKILL.md`) — roll Playwright Java to a new upstream version: bump the driver, regenerate the API, and port relevant upstream changes. +- **playwright-java-release** (`.claude/skills/playwright-java-release/SKILL.md`) — prepare a release after the rolling PR merges: cut the release branch, mark the Maven version, and draft the GitHub release.