API 历史介绍 (GSoC 2024)

2024 年 8 月 21 日 ·7 分钟阅读

Electron API 的历史变更现在将在文档中详细说明。

您好 👋，我是 Peter，Electron 的 2024 年 Google 编程之夏 (GSoC) 贡献者。

在 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 历史数据

设计原型 (已关闭)	设计原型 (已打开)

这是最终实现的设计的样子

demo3

几乎与原型相同。最重要的补充是使用了 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
lint-markdown-api-history.ts
- 用于根据自定义 YAML（技术上是 JSON）模式 lint YAML API 历史记录的脚本。
  - 有用的错误消息
  - 全面的文档 / 代码注释
  - 广泛的 ~~Jest~~ Vitest 测试
  - 良好的性能
- 在以下位置实现：electron/lint-roller#73
- 在以下位置使用：electron/electron#42982
preprocess-api-history.ts
- 执行简单的验证，以防不正确的 API 历史记录设法进入代码仓库。还剥离了包裹 API 历史记录块的 HTML 注释标签，因为 Docusaurus 无法解析它们。
- 在以下位置实现/使用：electron/website#594
transformers/api-history.ts
- 用于将 Markdown 文档文件中的 YAML API 历史记录块转换为 ~~Markdown/HTML~~ React 表格 (ApiHistoryTable.tsx) 的脚本。
- 在以下位置实现/使用：electron/website#594
ApiHistoryTable.tsx
- React 表格组件，用于在文档网站上显示解析的 API 历史数据。
  - 使用的样式遵循网站其余部分的设计。
  - 响应式、可访问且通常编写良好的 HTML、CSS 和 JS。
- 在以下位置实现/使用：electron/website#594
styleguide.md
- 新 API 历史文档系统的用法/样式指南部分。
  - 易于理解
  - 编写良好
  - 包含示例
- 在以下位置实现/使用：electron/electron#42982
api-history-migration-guide.md
- 新 API 历史文档系统的迁移指南。
  - 易于理解
  - 编写良好
  - 包含示例
- 在以下位置实现/使用：electron/electron#42982

结论

我很高兴能从事此功能，并能够从代码审查中获得宝贵的经验，并与团队讨论其各种实现细节。

我相信在文档中添加 API 历史记录将使使用 Electron 的开发人员的生活更加轻松，尤其是那些尝试从几年前的 Electron 版本迁移其现有应用程序的开发人员。

我还想衷心感谢我的导师

David Sanders (@dsanders11)
Keeley Hammond (@VerteDinde)
Erick Zhao (@erickzhao)

...以及 Electron 团队的其他成员，感谢他们回答我的问题并花时间为我的拉取请求提供反馈。非常感谢。

详情​

API 历史文档系统 / YAML 模式​

JavaScript 实现​

Electron 文档网站的 UI 和样式​

用法/样式指南​

迁移指南​

交付成果​

结论​

详情