API 歷史介紹 (GSoC 2024)

2024 年 8 月 21 日 ·7 分鐘閱讀

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

我相信使用 YAML 就像 Node.js 文件一樣是最好的方法，因為它易於閱讀。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 套件，其中包含用於提取、驗證/程式碼檢查和轉換文件中的 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）結構描述，檢查所撰寫的 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 歷史文件系統的使用方式/風格指南章節。
  - 容易理解
  - 撰寫良好
  - 包含範例
- 在以下項目中實作/使用：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 和樣式​

使用方式/風格指南​

遷移指南​

交付項目​

結論​