メインコンテンツへ飛ぶ

API 履歴の導入 (GSoC 2024)

· 読むのにかかる時間 1 分
piotrpdev
piotrpdev

Electron API の履歴がドキュメント内で詳解されるようになります。

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

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: "`trafficLightPosition` オプションが `customButtonOnHover` のウインドウで機能するようにしました。"
deprecated:
  - pr-url: https://github.com/electron/electron/pull/37094
    breaking-changes-header: deprecated-browserwindowsettrafficlightpositionposition
```
-->

* `position` [Point](structures/point.md)

信号機ボタンのカスタム位置を設定します。`titleBarStyle` が `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: `trafficLightPosition` オプションが `customButtonOnHover` のウインドウで機能するようにしました。
```
-->

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

「[...] この提案について、私たちが指摘したい重要な変更点が 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 履歴用の個別パッケージは不要かもしれません。」

提唱改訂後
提唱改訂後

— Piotr Płaczek (私)、Slack にて

最終的に、私たちは私の当初のアイデアを実行しないことに決めました。

「@Piotr Płaczek それは良さそうですね！ いずれにしても、2 つの実装間で多くのコードを共有すべきだとわかれば、後のイテレーションで別のモジュールにリファクタリングできると思います 🙂」

— Erick Zhao (@erickzhao)、Slack にて

代わりに、私たちは、それらに最も関連性の高いさまざまなツールを Electron のリポジトリへと分割しました。

Electron のドキュメントのウェブサイトの UI とスタイル​

私は当初、API の履歴データを表示するためのシンプルな表を提案していました。

デザインプロトタイプ (閉じ状態)デザインプロトタイプ (開き状態)
デモ1デモ2

最終的に実装されたデザインは次のようになります。

デモ3

これはプロトタイプとほぼ同じです。 最も重要な追加は、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/機械学習エンジニアにとっては楽しい仕事でしょうが、私にそのスキルはなく、誤って 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 チームの他のメンバーの方々にも感謝します。 大変お世話になりました。