API 歷史介紹 (GSoC 2024)

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

Electron API 的歷史變更現在將在文件中詳細說明。

嗨 👋，我是 Peter，Electron 的 2024 年 Google 程式碼夏日活動 (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（指向 main 的根 PR），而不是像提案中那樣的硬編碼版本字串。

這可以作為單一的事實來源，然後可用於導出確切的版本號，並且如果變更反向移植到其他分支，則無需對 main 進行進一步的文件變更。"

— 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
- 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 版本遷移過來的開發人員。

我也要衷心感謝我的導師

David Sanders (@dsanders11)
Keeley Hammond (@VerteDinde)
Erick Zhao (@erickzhao)

...以及 Electron 團隊的其他成員，感謝他們回答我的問題並花時間為我的提取請求提供回饋。非常感謝。

詳細資訊​

API 歷史文件系統 / YAML 結構描述​

JavaScript 實作​

Electron 文件網站的 UI 和樣式​

使用方式/樣式指南​

遷移指南​

交付項目​

結論​