Electron 文档指南¶

API 历史迁移¶

指南：docs/development/api-history-migration-guide.md 样式规则：docs/development/style-guide.md（参见“API 历史”部分） 模式：docs/api-history.schema.json Lint：npm run lint:api-history

格式¶

将 YAML 历史块直接放在 Markdown 标题之后、参数之前：

### `module.method(args)`

<!--
```YAML history
added:
  - pr-url: https://github.com/electron/electron/pull/XXXXX
```
-->

* `arg` type - Description.

查找 API 添加时间¶

• git log --all --reverse --oneline -S "methodName" -- docs/api/file.md — 查找添加方法名的第一个提交
• git log --reverse -L :FunctionName:path/to/source.cc — 追溯 C++ 实现历史
• git log --grep="keyword" --oneline — 查找引用 PR 的合并提交
• gh pr view <number> --repo electron/electron --json baseRefName — 验证 PR 的目标是 main（而不是 backport）
• 在历史块中始终使用 main 分支的 PR URL，而不是 backport PR

交叉引用破坏性变更¶

• 在 docs/breaking-changes.md 中搜索 API 名称，以查找弃用/移除
• 对 breaking-changes 条目使用 git blame，以查找关联的 PR
• 使用 breaking-changes.md 中的标题 ID 添加 breaking-changes-header 字段

放置规则¶

• 仅在实际 API 条目（带有反引号签名的方法、事件、属性）上添加块
• 不要为类似 ## Methods、### Instance Methods、## Events 的章节标题添加块
• 模块级块放在 # moduleName 标题之后、模块描述引用之前
• 对于影响多个 API 的变更，在每个受影响的顶级标题下添加一个块（参见样式指南“影响多个 API 的变更”）

关键细节¶

• added 和 deprecated 数组具有 maxItems: 1；changes 可以有多个条目
• changes 条目需要 description 字段；added/deprecated 不需要
• 用双引号包裹描述，以避免特殊字符导致 YAML 解析问题
• 早期 Electron API（2015 年之前）使用合并提交 PR（例如 Merge pull request #534）
• 非常早期的 API（2013-2014 年，例如 ipcMain.on、ipcRenderer.send）早于 GitHub PR——对这些跳过历史块
• 当多个 API 在同一 PR 中添加时，它们都引用同一个 PR URL
• Promise 化 PR（例如 #17355）计为带有描述的 changes 条目
• 这些 PR 是破坏性变更，其说明应为“此方法现在返回 Promise，而不是使用回调函数。”
• 已弃用随后从文档中移除的 API 不需要历史块（移除记录在 breaking-changes.md 中）