介绍 API 历史功能 (GSoC 2024)
Electron API 的历史变更现在将在文档中详细说明。
大家好 👋,我是 Peter,2024 年 Google 编程之夏 (GSoC) Electron 项目的贡献者。
在 GSoC 项目期间,我为 Electron 文档及其函数、类等实现了一个 API 历史功能,方式类似于 Node.js 文档:通过允许在 API 文档 Markdown 文件中使用一个简单但功能强大的 YAML 模式,并在 Electron 文档网站上美观地显示它。
详细信息
API 历史文档系统 / YAML 模式
在 Markdown API 文档中,函数/类/等 的历史记录现在直接放置在该项目标题之后,以由 HTML 注释封装的 YAML 代码块形式呈现。
#### `win.setTrafficLightPosition(position)` _macOS_
<!--
```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."
deprecated:
- pr-url: https://github.com/electron/electron/pull/37094
breaking-changes-header: deprecated-browserwindowsettrafficlightpositionposition
```
-->
* `position` [Point](structures/point.md)
Set a custom position for the traffic light buttons. Can only be used with `titleBarStyle` set to `hidden`.
我相信像 Node.js 文档那样使用 YAML 是最好的方法,因为它易于阅读。API 历史并不极其复杂,理想情况下应该尽可能易于编写和阅读。
上面显示的最终设计实际上与我最初提议的设计有显著不同
<!--
```YAML history
added: v10.0.0
deprecated: v25.0.0
removed: v28.0.0
changes:
- version: v13.0.0
pr-url: https://github.com/electron/electron/pull/26789
description: Made `trafficLightPosition` option work for `customButtonOnHover` window.
```
-->
一个大的变化是去除了版本号
"[...] 关于这项提案,我们想指出一个相当显著的变化,这是我们在审查提案时讨论中提出的。 [...]
[我们]决定,缺点最少的方法是只使用 PR URL (指向 main 的根 PR),而不是像提案中那样硬编码版本字符串。
这可以作为单一的事实来源,然后可以用于推导精确的版本号,并且如果更改被反向移植到其他分支,则无需在 main 上进行进一步的文档更改。"
— David Sanders (@dsanders11) 通过 Slack
我们也没有在 API 历史中包含删除,因为当一个 API 从 Electron 中删除时,它也会从文档中删除。
JavaScript 实现
我最初计划创建一个新的 @electron/docs-api-history-tools
npm 包,它将包含用于提取、验证/ lint 和转换文档文件中 API 历史的脚本。
在大约编码期开始前一周,经过与我的导师讨论后,我意识到这可能没有必要
"大家好,我在会议后一直在思考这个项目:考虑到
e/website
和e/lint-roller
的提取逻辑由于它们的依赖关系需要不同地处理,也许不需要为 API 历史功能单独创建一个包?"
建议 修订 — Piotr Płaczek (我) 通过 Slack
我们最终决定不执行我最初的想法
"@Piotr Płaczek 我觉得这没问题!我想如果我们发现无论如何都需要在两个实现之间共享大量代码,我们总可以在后续迭代中重构到单独的模块中🙂"
— Erick Zhao (@erickzhao) 通过 Slack
相反,我们将这些各种工具分散到与它们最相关的 Electron 仓库中
yaml-api-history-schema.json
- ->
electron/electron
(api-history.schema.json
)
- ->
lint-yaml-api-history.ts
- ->
electron/lint-roller
(lint-markdown-api-history.ts
)
- ->
extract-yaml-api-history.ts
- ->
electron/website
(preprocess-api-history.ts
)
- ->
yaml-api-history-to-markdown.ts
- ->
electron/website
(transformers/api-history.ts
) - ->
electron/website
(ApiHistoryTable.tsx
)
- ->
Electron 文档网站的 UI 和样式
我最初提议一个简单的表格来显示 API 历史数据
设计原型 (关闭) | 设计原型 (打开) |
---|---|
这是最终实现的显示效果
与原型基本相同。最重要的补充是使用了 语义化版本 (SemVer) 范围,选择此方式是为了更好地传达功能存在于哪些版本中 (感谢 Samuel Attard (@MarshallOfSound) 的建议!)。
这很重要,因为更改经常会在受支持的 Electron 发布线之间进行反向移植,例如,一个修复可能同时进入 Electron v32.0.0、v31.1.0 和 v30.2.0。这意味着它不存在于 v31.0.0 中,而用户可能会根据它存在于 v30.x.x 版本中而错误地推断出来。
使用/样式指南
我添加了一个专门用于编写新功能 API 历史文档的使用/样式指南。我详细描述了 YAML 模式的正确用法,提供了典型/有用的示例等。你可以在这里找到它。
迁移指南
由于现有 API 必须迁移到新的文档系统,我创建了一个迁移指南。它包含了开发人员在迁移旧 API 时必须执行的典型步骤:查看重大更改,浏览过去的发布版本,甚至可能查看旧的提交等。然后指导开发人员遵循使用/样式指南,为每个以前存在的类/函数等添加 API 历史文档。
遗憾的是,我无法想到一种有效自动化此过程的方法。这可能是一个适合 AI/ML 工程师的绝佳任务;然而,我不具备这些技能,而且太害怕不小心在 API 历史中引入幻觉。即使自动化了,信息最终可能仍然需要人工验证 😕。这项任务可能必须手动完成,按文件逐个进行,就像 Node.js 文档所做的那样。
交付物
-
api-history.schema.json
- 一个用于记录 API 历史的全面 YAML 模式,支持:
- 新增
- 弃用
- 更改
- 相关拉取请求链接
- 反向移植
- 建议于:electron/rfc#6
- 实现/使用于:electron/electron#42982
- 使用于:electron/website#594
- 一个用于记录 API 历史的全面 YAML 模式,支持:
-
lint-markdown-api-history.ts
- 用于根据自定义 YAML (技术上是 JSON) 模式 lint YAML API 历史的脚本。
- 有用的错误消息
- 全面的文档 / 代码注释
- 广泛的
JestVitest 测试 - 良好的性能
- 实现于:electron/lint-roller#73
- 使用于:electron/electron#42982
- 用于根据自定义 YAML (技术上是 JSON) 模式 lint YAML API 历史的脚本。
-
preprocess-api-history.ts
- 执行简单的验证,以防不正确的 API 历史信息进入仓库。还会剥离包裹 API 历史块的 HTML 注释标签,因为 Docusaurus 无法解析它们。
- 实现/使用于:electron/website#594
-
transformers/api-history.ts
- 用于将 Markdown 文档文件中的 YAML API 历史块转换为
Markdown/HTMLReact 表格 (ApiHistoryTable.tsx
) 的脚本。 - 实现/使用于:electron/website#594
- 用于将 Markdown 文档文件中的 YAML API 历史块转换为
-
ApiHistoryTable.tsx
- 用于在文档网站上显示解析后的 API 历史数据的 React 表格组件。
- 使用与网站其余部分设计一致的样式。
- 响应式、可访问且总体上编写良好的 HTML、CSS 和 JS。
- 实现/使用于:electron/website#594
- 用于在文档网站上显示解析后的 API 历史数据的 React 表格组件。
-
styleguide.md
- 新 API 历史文档系统的使用/样式指南部分。
- 易于理解
- 编写良好
- 包含示例
- 实现/使用于:electron/electron#42982
- 新 API 历史文档系统的使用/样式指南部分。
-
api-history-migration-guide.md
- 新 API 历史文档系统的迁移指南。
- 易于理解
- 编写良好
- 包含示例
- 实现/使用于:electron/electron#42982
- 新 API 历史文档系统的迁移指南。
结论
我很享受开发这个功能的过程,并从代码审查以及与团队讨论其各种实现细节中获得了宝贵的经验。
我相信在文档中添加 API 历史功能将大大简化 Electron 开发者的工作,特别是那些尝试将现有应用从几年前的 Electron 版本迁移过来的开发者。
我还要衷心感谢我的导师们:
- David Sanders (@dsanders11)
- Keeley Hammond (@VerteDinde)
- Erick Zhao (@erickzhao)
...以及 Electron 团队的其他成员,感谢他们回答我的问题并花时间为我的拉取请求提供反馈。我非常感激。