跳转到主要内容

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

·8 分钟阅读
piotrpdev
piotrpdev

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

嗨 👋，我是 Peter，2024 年的 Google 暑期代码大赛 (GSoC) 的 Electron 贡献者。

在 GSoC 项目期间，我为 Electron 文档及其函数、类等实现了一个 API 历史记录功能，类似于 Node.js 文档：允许在 API 文档 Markdown 文件中使用一个简单但强大的 YAML 模式，并在 Electron 文档网站上美观地显示它。

详情​

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

在 Markdown API 文档中，某个函数/类/等的历史记录现在以 YAML 代码块的形式直接放置在该条目的标题之后，并被 HTML 注释包裹。

#### `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 包，其中包含用于提取、验证/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

这是最终实现的设计

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

    • 用于 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

    • 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 团队的其余成员，感谢他们回答我的问题并花时间就我的拉取请求提供反馈。非常感谢。