跳到主要内容

API 历史介绍 (GSoC 2024)

·阅读时长 7 分钟
piotrpdev
piotrpdev

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

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

这可以作为单一事实来源，然后用于推导确切的版本号，并且如果更改被回溯到其他分支，主分支上就不需要进一步的文档更改了。"

— David Sanders (@dsanders11) 通过 Slack

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

JavaScript 实现​

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

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

"“大家好，我们在碰头会后一直在思考这个项目：考虑到 e/website 和 e/lint-roller 的提取逻辑因其依赖性需要以不同方式处理，也许没有必要为 API 历史相关内容创建一个单独的包？”"

提议的修改后的
proposedrevised

— Piotr Płaczek (我) 通过 Slack

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

"“@Piotr Płaczek，我觉得那样没问题！我认为如果我们发现无论如何都需要在两个实现之间共享大量代码，我们总可以在后续迭代中重构为一个单独的模块。"🙂"

— Erick Zhao ((@erickzhao) 通过 Slack

相反，我们将这些各种工具分配给了与它们最相关的 Electron 仓库中

Electron 文档网站的 UI 和样式设计​

我最初提议使用一个简单的表格来显示 API 历史数据

设计原型（关闭）设计原型（打开）
demo1demo2

这是最终实现的UI设计效果

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

  • lint-markdown-api-history.ts

    • 用于根据自定义 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

    • 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 版本迁移现有应用的开发者。

我还要衷心感谢我的导师们

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