Skip to main content

介绍 API 历史（GSoC 2024）

· 11 min read
piotrpdev

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

🌐 Historical changes to Electron APIs will now be detailed in the docs.

嗨 👋，我是彼得，2024 年 Google Summer of Code (GSoC) 的 Electron 贡献者。

🌐 Hi 👋, I'm Peter, the 2024 Google Summer of Code (GSoC) contributor to Electron.

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

🌐 Over the course of the GSoC program, I implemented an API history feature for the Electron documentation and its functions, classes, etc. in a similar fashion to the Node.js documentation: by allowing the use of a simple but powerful YAML schema in the API documentation Markdown files and displaying it nicely on the Electron documentation website.

细节​

🌐 Details

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

🌐 API history documentation system / YAML schema

在 Markdown API 文档中，函数/类等的历史记录现在直接放置在该项目的标题之后，以用 HTML 注释封装的 YAML 代码块的形式展示。

🌐 In the Markdown API documentation, the history for a function/class/etc. is now placed directly after the header for that item in the form of a YAML code block encapsulated by an HTML comment.


#### `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 历史并不是特别复杂，理想情况下应该尽可能容易编写和阅读。

🌐 I believe using YAML like the Node.js docs do was the best approach because it is easy to read. The API history isn't extremely complicated and should ideally be as easy to write and read as possible.

上面显示的最终设计实际上与我提出的方案有很大不同：

🌐 The final design shown above is actually significantly different to the one I proposed:

<!--
```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.
```
-->

一个重大变化是删除了版本号：

🌐 One large change is the removal of version numbers:

">‘[...] 我们想指出提案中有一个相当重要的变化，这是在我们审查提案时讨论中提出的。 [...]

[我们] 决定，缺点最少的方法是只使用 PR URL（指向主分支的根 PR），而不是像提案中那样使用硬编码的版本字符串。

这可以作为单一的真实来源，然后用于推导出准确的版本号，如果该变更被回溯到其他分支，则无需对主分支进行更多的文档更改。"

— David Sanders (@dsanders11) 通过 Slack

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

🌐 We also didn't include removals in the API History, since when an API is removed from Electron, it is also removed from the documentation.

JavaScript 实现​

🌐 JavaScript implementation

我原本计划创建一个新的 @electron/docs-api-history-tools npm 包，其中将包含用于提取、验证/格式检查以及转换文档文件中 API 历史记录的脚本。

🌐 I originally planned to create a new @electron/docs-api-history-tools npm package that would contain scripts for extracting, validating/linting and converting the API history in the documentation files.

大约在编码周期开始前一周，并且在与我的导师进行一些讨论之后，我意识到那可能是没有必要的：

🌐 About a week before the coding period began, and after some discussion with my mentors, I realized that was probably unnecessary:

“大家好，在我们的讨论之后，我在考虑这个项目：考虑到因为依赖的不同，e/website 和 e/lint-roller 中的提取逻辑需要不同处理，也许根本不需要为 API 历史相关的内容创建单独的包？”

提议修订
提议的修订

— Piotr Płaczek（我）通过 Slack

我们最终决定放弃我最初的想法：

🌐 We ultimately decided to not go ahead with my original idea:

“@Piotr Płaczek 我觉得这样没问题！我认为如果我们发现两个实现之间需要共享大量代码，我们总是可以在以后的迭代中将其重构到一个单独的模块中 🙂”

— Erick Zhao (@erickzhao) 通过 Slack

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

🌐 Instead, we divided those various tools across the Electron repos that were most relevant to them:

Electron 文档网站的 UI 和样式​

🌐 UI and styling for Electron documentation website

我最初建议用一个简单的表格来显示 API 历史记录数据：

🌐 I originally proposed a simple table to display the API History data:

设计原型（关闭）设计原型（打开）
演示1演示2

最终实现的设计如下：

🌐 This is what the final implemented design looks like:

demo3

几乎与原型相同。最显著的新增功能是使用了 SemVer 范围，这样的选择是为了更好地传达某个功能在哪些版本中存在（感谢 Samuel Attard (@MarshallOfSound) 的建议！）。

🌐 Pretty much the same as the prototype. The most significant addition is the use of SemVer ranges, which were chosen to better communicate which versions a feature is present in (thanks Samuel Attard (@MarshallOfSound) for the suggestion!).

这是重要的，因为更改常常会跨受支持的 Electron 发行版本回移，例如一个修复可能会出现在 Electron v32.0.0、v31.1.0 和 v30.2.0 中。这意味着它不会出现在 v31.0.0 中，而用户可能会错误地推断它存在于 v30.x.x 版本中。

🌐 This is important because changes are frequently backported across supported Electron release lines e.g. a fix may make it into Electron v32.0.0, v31.1.0 and v30.2.0. This means it is not present in v31.0.0 which a user might mistakenly deduce based on the fact it is present in a v30.x.x release.

使用/样式指南​

🌐 Usage/style guide

我增加了一份专门用于编写新功能 API 历史文档的使用/风格指南。我详细描述了 YAML 架构的正确用法，提供了典型的/有用的示例等。你可以在这里找到它。

🌐 I added a usage/style guide dedicated to writing API history documentation for new features. I described proper usages of the YAML schema in detail, provided typical/useful examples, etc. You can find it here.

迁移指南​

🌐 Migration guide

由于现有的 API 必须迁移到新的文档系统，我编写了一份迁移指南。它包含了开发者在迁移旧 API 时需要执行的典型步骤：查看重大变更、浏览过去的版本发布、可能还需要查看旧的提交记录等等。然后指导开发者按照使用/样式指南，为每个先前存在的类/函数/等添加 API 历史文档。

🌐 Since existing APIs have to be migrated to the new documentation system, I created a migration guide. It features the typical steps of what a developer has to do when migrating old APIs: looking through breaking changes, browsing through the past releases, maybe looking through old commits, etc. Then instructing the developer to follow the usage/style guide to add API history documentation for each previously existing class/function/etc.

可惜，我想不出有效自动化该进程的方法。这可能是一个人工智能/机器学习工程师的好任务；然而，我没有这些技能，而且也太担心会不小心在 API 历史中引入幻觉。即使实现了自动化，这些信息最终可能仍需由人工进行核实😕。这个任务可能不得不手动完成，逐个文件处理，就像为 Node.js 文档所做的那样。

可交付成果​

🌐 Deliverables

  • 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

结论​

🌐 Conclusion

我在开发这个功能时玩得很开心，并且通过代码审查以及与团队讨论各种实现细节获得了宝贵的经验。

🌐 I had a lot of fun working on this feature and was able to earn valuable experience from code reviews and discussing its various implementation details with the team.

我相信在文档中添加 API 历史记录将极大地简化使用 Electron 的开发者的工作，特别是那些尝试将现有应用从几年前的 Electron 版本迁移过来的开发者。

🌐 I believe the addition of API history to the documentation will make the lives of developers using Electron a lot easier, especially ones attempting to migrate their existing app from a several year old Electron version.

我还要真诚地感谢我的导师们：

🌐 I also want to sincerely thank my mentors:

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