docs(skills): rely on upstream release notes in the release skill (#3278)

Author: yury-s

.claude/skills/playwright-release/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playwright-release
-description: Prepare a Playwright Python release. Checks open bugs, writes the Python release notes in microsoft/playwright, opens the release PR, cuts the release branch, and saves a draft GitHub release. Never publishes the release.
+description: Prepare a Playwright Python release. Checks open bugs, adds Python-specific changes to the Python release notes in microsoft/playwright, opens the release PR, cuts the release branch, and saves a draft GitHub release. Never publishes the release.
 ---
 
 # Preparing a Playwright Python release
@@ -13,8 +13,8 @@ Remotes: find the remote for `microsoft/playwright-python` with `git remote -v`.
 The commands below call it `upstream`.
 
 What you may push:
-- The user's request to prepare the release is the instruction to open the two PRs
-  in steps 2 and 3.
+- The user's request to prepare the release is the instruction to open the PRs
+  in steps 2 and 3. Step 2 has a PR only when it adds Python changes.
 - Cut the release branch (step 4) only when the user tells you to.
 - Never publish the release.
 
@@ -39,45 +39,40 @@ API roll for 1.xx is already on `main`, that PR only moves `DRIVER_VERSION`.
 
 ## 2. Release notes (microsoft/playwright)
 
-Write the notes in the roll checkout, on a branch from `origin/main`:
+The Python notes in `docs/src/release-notes-python.md` are written in
+`microsoft/playwright` together with the Node.js notes. The
+`playwright-release-notes` skill there
+(`$PW_SRC_DIR/.claude/skills/playwright-release-notes/SKILL.md`) covers that,
+including the Python code style. Check that the `## Version 1.xx` section is on the
+release branch:
+
+```sh
+git -C "$PW_SRC_DIR" fetch origin release-1.xx
+git -C "$PW_SRC_DIR" show FETCH_HEAD:docs/src/release-notes-python.md | grep -n '^## Version 1.xx$'
+```
+
+If it is missing, tell the user: it should have landed with the Node.js notes.
+
+Then lean towards Python. List the playwright-python commits since the previous
+release branch:
+
+```sh
+gh api repos/microsoft/playwright-python/compare/release-1.<xx-1>...main \
+  --jq '.commits[].commit.message | split("\n")[0]'
+```
+
+Pick only significant changes that only the Python port has, for example a
+different exception type. Leave out minor bug fixes, internal changes, and anything
+the notes already cover. If nothing is significant, go to step 3. Otherwise list
+the changes for the user and ask whether to add them to the notes.
+
+To add them, write them in the roll checkout, on a branch from `origin/main`:
 
 ```sh
 git -C "$PW_SRC_DIR" fetch origin main
 git -C "$PW_SRC_DIR" checkout -b release-notes-1.xx-python origin/main
 ```
 
-In `docs/src/release-notes-python.md`, add a `## Version 1.xx` section above the
-previous version. Translate it from the `## Version 1.xx` section of
-`docs/src/release-notes-js.md`. Compare the `Version 1.63` sections of the two
-files to see what a past translation dropped and changed.
-
-- Keep the structure: highlights with emoji headings, `### New APIs` with
-  `####` groups, `### Announcements`, `### Browser Versions`.
-- Remove what Python does not have: the test runner (`@playwright/test`,
-  `test.*`, config, fixtures, projects, reporters), UI mode, the HTML report,
-  component testing, the VS Code extension, and `npx playwright test` options.
-  Remove every API whose `langs` excludes Python. To check an API, look for it in
-  `playwright/async_api/_generated.py`, or check `langs` in `api.json` (see
-  "Verifying classifications" in the `playwright-roll` skill).
-- Rewrite code samples in Python, with the sync API:
-  `page.get_by_role("button").click()`. Use snake_case names and Python values
-  (`True`, `None`).
-- Keep API links as docs link macros: `` [`method: Page.frameLocator`] ``,
-  `` [`option: Tracing.start.ariaSnapshots`] ``,
-  `` [`event: Page.dialogClosed`] ``. The docs site shows them with Python names.
-  In plain text, use Python names.
-- Commands: write `playwright install`, not `npx playwright install`.
-- Lean towards Python. List the playwright-python commits since the previous
-  release branch:
-
-  ```sh
-  gh api repos/microsoft/playwright-python/compare/release-1.<xx-1>...main \
-    --jq '.commits[].commit.message | split("\n")[0]'
-  ```
-
-  If some of them change what users see (for example, a different exception
-  type), list them for the user and ask whether to add them to the notes.
-
 Commit, push to the user's fork of `microsoft/playwright`, and open the PR. If
 the checkout has no remote for the fork, add one. `gh api user --jq .login`
 gives the user's login.
@@ -87,9 +82,12 @@ git -C "$PW_SRC_DIR" commit -am "docs: release notes for v1.xx Python"
 git -C "$PW_SRC_DIR" push <fork-remote> release-notes-1.xx-python
 gh pr create --repo microsoft/playwright --head <login>:release-notes-1.xx-python \
   --title "docs: release notes for v1.xx Python" \
-  --body "- Add \`Version 1.xx\` to the Python release notes, translated from the Node.js notes"
+  --body "- Update the \`Version 1.xx\` Python release notes with upstream and Python-specific changes"
 ```
 
+After the PR merges, it needs a cherry-pick to `release-1.xx` (the
+`playwright-cherry-pick` skill in `microsoft/playwright`).
+
 Then put the roll checkout back on the release branch. `./scripts/update_api.sh`
 reads the docs from it. Run the checkout checks from step 2 of the
 `playwright-roll` skill.
@@ -104,28 +102,14 @@ Open a PR from the branch with the roll commit:
 
 - Title: `chore: roll Playwright to v1.xx.y`, where `v1.xx.y` is the Python
   release version, even when `DRIVER_VERSION` is a beta build.
-- Description: the release notes from step 2, in GitHub markdown (see below).
+- Description: the Python release notes, in GitHub markdown (see below).
   The user copies this description into the GitHub release, so for this PR it
   replaces the "keep PR descriptions short" rule in `AGENTS.md`.
 
-Convert the notes to GitHub markdown yourself:
-
-- Leave out the `## Version 1.xx` heading. Move every other heading up one level
-  (`###` becomes `##`, `####` becomes `###`).
-- Replace each link macro with a full playwright.dev link. Use the Python name as
-  the link text:
-
-  | Macro | GitHub markdown |
-  |---|---|
-  | `` [`method: Page.frameLocator`] `` | `[page.frame_locator()](https://playwright.dev/python/docs/api/class-page#page-frame-locator)` |
-  | `` [`method: Locator.visible`] `` (a property in Python) | `[locator.visible](https://playwright.dev/python/docs/api/class-locator#locator-visible)` |
-  | `` [`option: Browser.newContext.httpCredentials`] `` | ``[`http_credentials`](https://playwright.dev/python/docs/api/class-browser#browser-new-context-option-http-credentials)`` |
-  | `` [`event: BrowserContext.dialogClosed`] `` | `[browser_context.on("dialogclosed")](https://playwright.dev/python/docs/api/class-browsercontext#browser-context-event-dialog-closed)` |
-
-  The page is `class-` and the class name in lower case. The anchor is the class
-  and member names in kebab-case. Options add `-option-<name>`, and events add
-  `-event-<name>`. A member is a property in Python if `_generated.py` declares
-  it with `@property`.
+Convert the `## Version 1.xx` section of `release-notes-python.md` on
+`release-1.xx` to GitHub markdown with Python link text. Follow step 3 of the
+`playwright-release-notes` skill in `microsoft/playwright`, including its link
+check and the Python scan.
 
 Wait for the user to review and merge the PR. Do not merge it yourself.