SuperAPI AI 工具集

playwright-release-notes

写作与研究

查看项目

更新于 10-21 16:48

技能介绍

用途

该技能用于为 Playwright 的一个新版本撰写发布说明。每个版本需要在 docs/src/ 下的四个文件中各添加一个 ## Version 1.xx 章节:Node.js 的 release-notes-js.md,以及 Python、Java、.NET 的翻译版本 release-notes-python.md、release-notes-java.md、release-notes-csharp.md。四种语言的说明应在同一个 PR 中完成,以便各语言在开始发布时都已有对应说明;各语言仓库随后只补充自己特有的重要变更,并各自从自己的章节生成 GitHub release。

主要能力

  • 撰写 Node.js 发布说明:在 release-notes-js.md 中于上一版本之上新增 ## Version 1.xx 章节,结构依次为亮点(每个带 emoji 标题和简短示例)、### New APIs(含 #### 分组)、### Breaking Changes ⚠️、### Announcements 和 ### Browser Versions。浏览器版本通过 node utils/print_versions.js 打印。
  • 使用文档链接宏引用 API,例如 [method: Page.frameLocator]、[property: Page.webmcp]、[event: Page.dialogClosed]、[option: Tracing.start.ariaSnapshots]、[Locator],各语言文档会以该语言的名称显示。其他文档页面使用相对路径链接,如 test locks。
  • 翻译为 Python、Java、.NET:从 Node.js 章节翻译,保持相同结构,并参照各文件 Version 1.63 章节了解过往翻译的取舍。
  • 按语言删除不存在的功能:测试运行器(@playwright/test、test.*、config、fixtures、projects、reporters 及 npx playwright test 选项)、UI 模式、HTML 报告、组件测试、VS Code 扩展、TypeScript 专属特性(泛型、JSX、tsconfig)和设备描述符,以及 langs 不包含该语言的 API(在 docs/src/api/ 中检查 langs,方法间共享选项定义在 docs/src/api/params.md)。
  • 使用各语言特有的 API 名称:语言特有选项有自己的 langs(如 recordVideoFps 为 langs: csharp, java, python,而 Node.js 为 recordVideo.fps);alias-<lang> 可重命名成员(如 alias-java: isVisible 对应 LocatorAssertions.toBeVisible)。生成的 API 可在同级检出中确认:../playwright-python/playwright/sync_api/_generated.py、../playwright-java/playwright/src/main/java/com/microsoft/playwright/、../playwright-dotnet/src/Playwright/API/Generated/。
  • 当 Node.js 示例通过 playwright.config.ts 展示库功能时,改为展示 API 调用(如 1.64 的视频配置改为调用 Screencast.start 和 Screencast.showActions)。
  • 按各语言风格改写代码示例,基础设施工作流会检查 python、java、csharp 片段的语法。
  • 生成 GitHub release markdown:去掉 ## Version 1.xx 标题,其余标题上移一级(### 变 ##,#### 变 ###);将链接宏替换为完整链接(语言文档基础 URL 加路径),链接文本使用该语言名称;图片相对路径改为 GitHub 完整地址。
  • 校验链接可解析,并扫描未转换内容、链接文本中的多余空格等问题。

使用方式

  1. 在 docs/src/release-notes-js.md 中新增 ## Version 1.xx 章节,参照上一版本撰写亮点、New APIs、Breaking Changes、Announcements 和 Browser Versions。
  2. 在三个翻译文件中新增对应 ## Version 1.xx 章节,按各语言规则翻译并调整代码示例。
  3. 为四个文件开一个 PR,标题为 docs: release notes for v1.xx;合并后使用 playwright-cherry-pick 技能将其 cherry-pick 到 release-1.xx。
  4. 各仓库从 release-1.xx 上自己的 ## Version 1.xx 章节转换出 GitHub release markdown。

各语言的代码风格要点:

  • Python:使用同步 API,如 page.get_by_role("button").click();snake_case 名称;Python 值 True、False、None;选项为关键字参数;对象和数组为 dict 和 list;事件为 page.on("dialogclosed", handler);断言为 expect(locator).to_have_text([...]);使用 alias-python 名称如 route.continue_()、locator.or_()、page.expect_request();命令写 playwright install。
  • Java:无 await、双引号、分号、类型化局部变量;选项用 builder,如 new Screencast.StartOptions().setPath(Paths.get("video.webm")).setFps(60);对象字面量用值类如 new Cookie("session-id", "42").setUrl(url);数组用 Arrays.asList 或 new String[];属性用 getter 如 page.webmcp();事件用 page.onDialogClosed(handler);断言用 assertThat(locator).hasText(...);使用 alias-java 成员如 route.resume();命令用 mvn exec:java ...。
  • .NET:PascalCase 成员、异步方法带 Async 后缀、var 局部变量、双引号、分号;选项用初始化器 new() { Path = "video.webm", Fps = 60 };嵌套对象用 Size = new() { Width = 1920, Height = 1080 };对象字面量用 new Cookie { Name = "session-id", Value = "42", Url = url };数组用 new[] { "a", "b" };字符串字面量联合值用枚举成员如 AriaSnapshotMode.Ai;属性用 page.Webmcp;事件用 page.DialogClosed += (_, dialog) => { ... };断言用 await Expect(locator).ToHaveTextAsync(...);使用 alias-csharp 成员如 page.APIRequest;命令用 pwsh bin/Debug/netX/playwright.ps1 install --no-remove。

适用场景

适用于 Playwright 项目维护者或文档贡献者,在准备新版本发布时统一撰写和翻译四种语言的发布说明,并生成各语言仓库的 GitHub release 内容。

限制

  • 各语言需删除其不具备的功能与 API,不能照搬 Node.js 内容。
  • 不得添加仅由某语言移植引入的变更,这些由语言仓库自行补充。
  • 相对链接必须指向该语言存在的页面(*-js.md 页面仅限 Node.js)。
  • 链接锚点使用 docs/src/api/ 中的名称,即使某语言重命名了成员。
  • 需检查所有链接可解析,并确保无未转换的宏、残留空格等问题。
  • 若转换中发现说明本身的问题(如某语言没有的 API 或风格错误的示例),需回到步骤 2 修正说明。