`module.method(args)`

module.method(args)

• arg type - Description.

[docs/development/style-guide.md](https://gitcode.com/GitHub_Trending/el/electron/blob/ffc6f4d5ad358776d40241cbec382ed4a8282270/docs/development/style-guide.md?utm_source=gitcode_repo_files) 中给出了更精细的排版要求（两空格缩进、不使用 YAML 注释、标题与块之间必须有空行）：

```markdown
API HEADER                |  #### `win.setTrafficLightPosition(position)` _macOS_
BLANK LINE                |
HTML COMMENT OPENING TAG  |  <!--
API HISTORY OPENING TAG   |  ```YAML history
API HISTORY               |  added:
                          |    - pr-url: https://github.com/electron/electron/pull/22533
API HISTORY CLOSING TAG   |  ```
HTML COMMENT CLOSING TAG  |  -->
BLANK LINE                |
```

### Schema 定义的字段规则

[docs/api-history.schema.json](https://gitcode.com/GitHub_Trending/el/electron/blob/ffc6f4d5ad358776d40241cbec382ed4a8282270/docs/api-history.schema.json?utm_source=gitcode_repo_files) 基于 JSON Schema draft-07，其结构（对照源码逐字段说明）：

- **`added`**：数组，`minItems: 1` 且 `maxItems: 1` —— 一个 API 只能被添加一次；
- **`deprecated`**：数组，`minItems: 1` 且 `maxItems: 1` —— 同理只能弃用一次；
- **`changes`**：数组，`minItems: 1`，**无上限**，可以记录多次修改；
- 三个数组的条目都继承 `baseChangeSchema`，公共字段为：
  - `pr-url`（**必填**）：必须是匹配 `^https://github.com/electron/electron/pull/\d+$` 的主分支 PR 地址，**不能是 backport PR**；
  - `breaking-changes-header`（可选）：对应 `breaking-changes.md` 中条目的标题 ID（`minLength: 3`）；
  - `description`（可选，`minLength: 3`、`maxLength: 120`）：变更的简短描述；
- **`changes` 条目额外强制要求 `description`**（schema 中通过 `changesChangeSchema` 的 `required: ["description"]` 实现），而 `added`/`deprecated` 不要求；
- `additionalProperties: false`：不允许出现未定义的字段。

这与 `docs/CLAUDE.md` 的 "Key details" 章节完全对应：`added` 和 `deprecated` 数组有 `maxItems: 1`，`changes` 可以有多个条目；`changes` 条目必须带 `description` 字段，`added`/`deprecated` 不需要。

仓库中已有大量真实样例可参考。例如 [docs/api/browser-view.md](https://gitcode.com/GitHub_Trending/el/electron/blob/ffc6f4d5ad358776d40241cbec382ed4a8282270/docs/api/browser-view.md?utm_source=gitcode_repo_files) 开头的模块级块：

```markdown
# BrowserView

<!--
```YAML history
deprecated:
  - pr-url: https://github.com/electron/electron/pull/35658
    breaking-changes-header: deprecated-browserview
```
-->
```

而 [docs/api/context-bridge.md](https://gitcode.com/GitHub_Trending/el/electron/blob/ffc6f4d5ad358776d40241cbec382ed4a8282270/docs/api/context-bridge.md?utm_source=gitcode_repo_files) 则展示了 "变更影响多个 API" 的场景（见第四节）。

## 三、放置规则（Placement rules）

`docs/CLAUDE.md` 给出了三条硬性放置规则，lint 脚本的 `--check-placement` 参数正是用来机器化校验它们的：

1. **只加在真实 API 条目上**：即带有反引号签名的方法、事件、属性（如 `#### win.foo(bar)`）；
2. **不要加在章节标题上**：如 `## Methods`、`### Instance Methods`、`## Events` 这类纯组织性标题；
3. **模块级块放在 `# moduleName` 标题之后、模块描述引文（blockquote）之前**。

对于**一个变更影响多个 API** 的情况（参见 [docs/development/style-guide.md](https://gitcode.com/GitHub_Trending/el/electron/blob/ffc6f4d5ad358776d40241cbec382ed4a8282270/docs/development/style-guide.md?utm_source=gitcode_repo_files) "Change affecting multiple APIs" 小节），做法是在**每个受影响 API 的顶层标题下各加一个块**，例如 PR #40330（`ipcRenderer` 不能再经 `contextBridge` 传递）分别在 [docs/api/context-bridge.md](https://gitcode.com/GitHub_Trending/el/electron/blob/ffc6f4d5ad358776d40241cbec382ed4a8282270/docs/api/context-bridge.md?utm_source=gitcode_repo_files) 与 [docs/api/ipc-renderer.md](https://gitcode.com/GitHub_Trending/el/electron/blob/ffc6f4d5ad358776d40241cbec382ed4a8282270/docs/api/ipc-renderer.md?utm_source=gitcode_repo_files) 的 `#` 级标题下放置了相同的 history 块。注意 style guide 特别指出：`contextBridge.exposeInMainWorld(apiKey, api)` 本身没有被修改（只是其可用参数变少了），因此**没有**在该方法上另加块——这是判断"改的是 API 本身还是 API 的用法"的典型边界案例。

## 四、如何查证"某个 API 何时被添加"

`docs/CLAUDE.md` 给出了四条常用命令：

```bash
# 1. 找到 docs 中首次出现方法名的提交（-S 按内容出现计数变化定位）
git log --all --reverse --oneline -S "methodName" -- docs/api/file.md

# 2. 追踪 C++ 实现的历史（直接看源码函数何时出现）
git log --reverse -L :FunctionName:path/to/source.cc

# 3. 用关键词找引用了 PR 的合并提交
git log --grep="keyword" --oneline

# 4. 用 gh 确认 PR 目标分支是 main 而不是 backport
gh pr view <number> --repo electron/electron --json baseRefName
```

配合规则：**history 块中一律使用 main 分支的 PR URL，而不是 backport PR 的 URL**。`gh pr view --json baseRefName` 这一步就是用来确认该 PR 是直接向 main 发起的，避免误填 release 分支的 backport 链接（schema 的 `pr-url` 注释也明确了这一点：*"URL to the 'main' GitHub Pull Request for the change (i.e. not a backport PR)"*）。

[docs/development/api-history-migration-guide.md](https://gitcode.com/GitHub_Trending/el/electron/blob/ffc6f4d5ad358776d40241cbec382ed4a8282270/docs/development/api-history-migration-guide.md?utm_source=gitcode_repo_files) 则以 `BrowserWindow.getTrafficLightPosition()` 为例走完了完整流程：先用 `git log -L :GetTrafficLightPosition:shell/browser/native_window_mac.mm` 找到引入实现的提交（`feat: programmatically modify traffic light positioning (#22533)`），再用 `git checkout <commit>^` 回退验证上一提交中该 API 确实不存在，最后生成如下完整的 history 块：

````markdown
#### `win.getTrafficLightPosition()` _macOS_ _Deprecated_

<!--
```YAML history
added:
  - pr-url: https://github.com/electron/electron/pull/22533
changes:
  - pr-url: https://github.com/electron/electron/pull/26789
    description: "Made `trafficLightPosition` option work for `customButtonOnHover` window."
    breaking-changes-header: behavior-changed-draggable-regions-on-macos
deprecated:
  - pr-url: https://github.com/electron/electron/pull/37878
    breaking-changes-header: deprecated-browserwindowgettrafficlightposition
```
-->

这个样例把三类条目（added + changes 带 description + deprecated 带 breaking-changes-header）组合在一起，恰好覆盖了 schema 的全部字段语义，适合作为模板背诵。

五、与 breaking-changes.md 交叉引用

当一个变更属于破坏性变更时，history 块需要通过 breaking-changes-header 字段挂接到 docs/breaking-changes.md 中的对应条目。docs/CLAUDE.md 给出的操作流程：

1. 在 docs/breaking-changes.md 中按 API 名搜索，找到对应的 deprecation/removal 条目（该文档全文约 3400 行，条目形如 ### Deprecated: BrowserWindow.getTrafficLightPosition()）；
2. 对该条目执行 git blame，定位写入它的提交，从而找到关联 PR；
3. 使用 breaking-changes.md 中该条目的标题 ID（GitHub 生成的 anchor，如 deprecated-browserwindowgettrafficlightposition）填入 breaking-changes-header。

迁移指南中的完整命令序列示范了这一过程：

$ grep -n "BrowserWindow.getTrafficLightPosition" docs/breaking-changes.md
523:### Deprecated: `BrowserWindow.getTrafficLightPosition()`
525:`BrowserWindow.getTrafficLightPosition()` has been deprecated, the

$ git blame -L523,524 -- docs/breaking-changes.md
1e206deec3e (Keeley Hammond 2023-04-06 ... ) ### Deprecated: ...

$ git log -1 1e206deec3e
    docs: update E24/E25 breaking changes (#37878)  <-- 关联的 PR

lint:api-history 的 --breaking-changes-file 参数会在 lint 时反查该 header 是否存在于 breaking-changes.md，因此手误写错 anchor 会被直接拦下。

六、Key details：容易踩坑的细节

docs/CLAUDE.md 最后汇总了一批无法从 schema 机器化体现、需要靠经验判断的规则，这里逐条展开：

• 双引号包裹 description：描述文本必须用双引号包起来，避免 YAML 解析被 [、] 等特殊字符破坏（style guide 中同样强调了这一点）。
• 早期 Electron API（2015 年之前）：当时的合并记录是 merge-commit 形式的 PR（如 Merge pull request #534），找 PR 号的方式要相应调整。
• 超早期 API（2013–2014 年）：例如 ipcMain.on、ipcRenderer.send 等早于 Electron 项目使用 GitHub PR 的时期，直接跳过，不写 history 块。
• 同一 PR 引入多个 API：这些 API 的 history 块引用同一个 PR URL。
• Promisification 类 PR（如 #17355）：Promise 化改造属于 changes 条目且必须带 description，且由于它改变了调用方式，属于破坏性变更，description 应写为 "This method now returns a Promise instead of using a callback function."
• 已弃用并从文档中删除的 API：不需要 history 块，因为其删除记录已在 breaking-changes.md 中体现。

七、写作描述（description）的风格约定

虽然 docs/CLAUDE.md 只写了"用双引号包起来"，但 docs/development/style-guide.md 补充了更完整的描述写作规范，撰写 changes 条目的 description 时应遵循：

• 面向应用开发者描述影响（而非实现细节）；
• 首字母大写、有标点、使用过去时；
• 尽量简洁（schema 限制最长 120 字符），理想情况是与 breaking-changes.md 中对应条目的标题保持一致；
• 优先复用关联 PR 的 release notes 措辞；
• 详细上下文读者可以去查 breaking-changes 文档或 PR 本身，description 不必面面俱到。

八、验证与收尾

改动文档后运行以下命令做完整校验（定义见 package.json）：

# 仅校验 API History 块
npm run lint:api-history

# 完整文档 lint（含 JS-in-Markdown、类型检查、fiddles、相对链接、Markdown 规范、API History）
npm run lint:docs