API 历史记录功能介绍 (GSoC 2024)

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

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

你好 👋，我是 Peter，2024 年 Google Summer of Code (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（到主分支的根 PR），而不是像提案中那样硬编码版本字符串。

这可以作为一个单一的真实来源，然后用于推导出确切的版本号，如果更改被反向移植到其他分支，则无需在主分支上进一步修改文档。"

— David Sanders (@dsanders11) via Slack

我们也没有包含 API 历史记录中的删除项，因为当 API 从 Electron 中删除时，它也会从文档中删除。

JavaScript 实现

我最初计划创建一个新的 @electron/docs-api-history-tools npm 包，其中包含用于提取、验证/ linting 和转换文档文件中 API 历史记录的脚本。

在编码期开始前大约一周，在与我的导师讨论后，我意识到这可能是不必要的

"大家好，我在我们的小组会议后思考了这个项目：考虑到 e/website 和 e/lint-roller 由于它们的依赖关系，提取逻辑需要分别处理，也许 API 历史记录部分不需要单独的包？"

提议修订

— Piotr Płaczek (我) via Slack

我们最终决定不采用我最初的想法

"@Piotr Płaczek 我觉得这样可以！如果我们发现两个实现之间需要共享很多代码，我们总可以在后续迭代中将其重构为一个单独的模块。🙂"

— Erick Zhao (@erickzhao) via 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
- 一个全面的 YAML 架构，用于记录 API 历史记录，包括支持
  - 添加
  - 弃用
  - 更改
  - 指向相关拉取请求的链接
  - 反向移植
- 已在: electron/rfc#6 中提出
- 已在: electron/electron#42982 中实现/使用
- 已在: electron/website#594 中使用
lint-markdown-api-history.ts
- 用于 linting 根据自定义 YAML（技术上是 JSON）架构编写的 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
- 用于在文档网站上显示解析后的 API 历史记录数据的 React 表格组件。
  - 使用符合网站其余设计风格的样式。
  - 响应式、无障碍且总体编写良好的 HTML、CSS 和 JS。
- 已在: electron/website#594 中实现/使用
styleguide.md
- 用于新的 API 历史记录文档系统的新 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 和样式​

使用/样式指南​

迁移指南​

交付物​

结论​