本文へスキップ

API履歴の紹介 (GSoC 2024)

·7分間の読書
piotrpdev
piotrpdev

Electron APIの履歴変更は、今後ドキュメントで詳しく説明されます。

こんにちは 👋、私はPeterです。2024年のGoogle Summer of Code (GSoC)のElectronコントリビューターです。

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

大きな変更の1つは、バージョン番号の削除です。

"[...]提案について、提案をレビューしていた際に議論の中で出てきた、ある程度重要な変更点が1つあります。[...]

[私たちは]、[最も少ない]欠点を持つアプローチは、提案のようにハードコードされたバージョン文字列の代わりにPR URL（mainへのルートPR）のみを使用することだと判断しました。

これは単一の真実の情報源として機能し、それから正確なバージョン番号を導き出すことができます。変更が他のブランチにバックポートされた場合、mainでのドキュメントの変更は不要になります。"

— David Sanders (@dsanders11) Slack経由

また、APIがElectronから削除されると、ドキュメントからも削除されるため、API履歴に削除を含めませんでした。

JavaScript実装​

当初、ドキュメントファイル内のAPI履歴を抽出、検証/Lint、変換するためのスクリプトを含む新しい@electron/docs-api-history-tools npmパッケージを作成する予定でした。

コーディング期間が始まる約1週間前、メンターとの議論の後、それはおそらく不要だと気づきました。

"皆さん、ハドルの後、プロジェクトについて考えていました。抽出ロジックは、依存関係のためにe/websiteとe/lint-rollerで異なる方法で処理する必要があることを考えると、API履歴の処理のために別のパッケージは必要ないかもしれませんか？"

提案改訂版
proposedrevised

— Piotr Płaczek (私) Slack経由

最終的に、私の元のアイデアを進めないことにしました。

"@Piotr Płaczek それは問題ないと思います！2つの実装間で多くのコードを共有する必要があるとわかった場合は、後で別々のモジュールにリファクタリングできます。🙂"

— 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リリースに含まれているという事実から、誤ってv31.0.0にも含まれていると推測する可能性があります。

使用方法/スタイルガイド​

新しい機能の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履歴をlintするためのスクリプト。
      • 分かりやすいエラーメッセージ
      • 包括的なドキュメント/コードコメント
      • 広範なJest Vitestテスト
      • 良好なパフォーマンス
    • 実装箇所: electron/lint-roller#73
    • 使用箇所: electron/electron#42982

  • preprocess-api-history.ts

    • 誤ったAPI履歴がリポジトリに含まれてしまった場合に備えて、簡単な検証を実行します。Docusaurusが解析できないため、API履歴ブロックを囲むHTMLコメントタグも削除します。
    • 実装/使用箇所: 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バージョンから既存のアプリを移行しようとしている開発者の生活が大幅に楽になると思います。

また、メンターの皆さんに心から感謝申し上げます。

…そして、Electronチームの他の皆さんにも、私の質問に答えていただき、プルリクエストに関するフィードバックをいただく時間を割いていただき、本当に感謝しています。