このドキュメントでは、新しいプラグインを作成する方法について説明します。このプロセスはファーストパーティ プラグインの作成を対象としていますが、サードパーティ プラグインの作成のガイドラインとしても使用できます。
プラグインの概要については、プラグインをご覧ください。
プラグインの作成の概要については、プラグインの作成方法に関する講演（2021 年）をご覧ください。
ファースト パーティとサードパーティ
プラグインの対象ユーザーは、npm を通じてプラグインを見つけて使用するデベロッパーです。
ファーストパーティ プラグインは Blockly チームによってサポートされ、npm の @blockly スコープで公開されています。幅広い Blockly アプリケーションで使用できるように設計されており、安定していて使いやすいです。これらは blockly-samples に保存されています。モーター速度を設定するフィールドは、多くのロボット プロジェクトで使用される可能性があり、ファーストパーティ プラグインの候補として適しています。
サードパーティ製プラグインは、個別にメンテナンスおよび公開されます。より複雑なもの、より実験的なもの、Blockly アプリケーションのより狭い範囲を対象としたものなどがあります。データベース スキーマで定義された特定のオブジェクトを編集するフィールドは、サードパーティ製プラグインとして作成することをおすすめします。
ファーストパーティの条件
ファーストパーティ プラグインは、次の要件を満たしている必要があります。
- Blockly チームから免除が認められない限り、すべての主要プラットフォームで動作します。
- Chrome、Firefox、Safari、Edge
- 最初の 1 年間はバグの処理を担当してくれる著者がいる。
- Blockly をモンキーパッチしないでください。
- 明確に定義され、文書化された API を備えている。
- Blockly チームから免除が認められない限り、Blockly コアから非公開関数やパッケージ関数を呼び出さないでください。
- 定義したサブクラスでパッケージ関数をオーバーライドすることは許可されています。
- 免除をご希望の場合は、blockly-samples の問題でお問い合わせください。
- テストを追加できる。
プロセス
プラグインは、提案、議論、実装、公開の 4 つの段階を経ます。
候補
プラグインは候補として開始されます。プラグインを提案するには、機能リクエスト テンプレートを使用して新しい問題を登録します。詳しくは、機能リクエストを作成する方法をご覧ください。
基本的な機能リクエスト情報に加えて、プラグインの提案には次の情報を含める必要があります。
- プラグインが公開する API。
- プラグインをサポートするためにコア Blockly で追加または変更する必要がある API。
- プラグインに UI 機能が含まれている場合は、スクリーンショット、GIF、モックアップ。
- サードパーティ製プラグインではなくファーストパーティ製プラグインであるべき理由の説明。
Blockly チームは、提案が届き次第確認し、問題をクローズするか、ファーストパーティ プラグインとして適切であると判断します。
ディスカッション
次に、プラグインは議論フェーズに入ります。このフェーズには、次のものが含まれます。
- 必要な機能の明確化。
- プラグインの API の説明。
- 実装の計画。
- テストの計画。
- コア Blockly の API 変更に関するディスカッション。
- 大きなプラグインを実装手順に分割する。
- 命名規則に基づくプラグインの命名。
- すべてのファースト パーティ基準が満たされていることを確認します。
通常、このディスカッションは GitHub の問題で行われます。プラグインの範囲が小さいほど、ディスカッション フェーズを迅速に進めることができます。大規模なプラグインは、コミュニティの注目を集め、適切なソリューションについて強い意見が寄せられる可能性があります。この状態になったら、おめでとうございます。人々が関心を持っているものを見つけたのです。
このフェーズの目標は、ディスカッションの終了までに、主要な設計上の決定がすべて行われ、実装手順の明確なリストが作成されることです。両方とも、問題のコメントに記録する必要があります。
議論の中で、プラグインをサードパーティ製プラグインとし、@blockly スコープで公開しないことを決定する場合があります。その場合は、理由を説明して問題をクローズします。
ディスカッションが完了すると、Blockly チームのメンバーが実装の準備ができたことをメモします。
実装
実装の手順は次のとおりです。
npx @blockly/create-packageを実行して、テンプレートからプラグインとそのディレクトリを設定します。詳細...- プラグインのコアロジックを実装します。
- 必要に応じて UI を実装します。
- Mocha を使用してプラグインをテストする。
READMEを含むプラグインのドキュメント化。
提案されたプラグインの実装が承認され、その作業に取り組みたい場合は、問題にコメントして、まだ貢献を受け付けているかどうかを確認してください。
実装は複数のコントリビューターが並行して行うことができます。プラグインは、独自のフォークで共同で実装することも、このリポジトリに対する pull リクエストを通じて実装することもできます。このリポジトリでプラグインの共同作業を行う場合は、Blockly チームに機能ブランチの作成を依頼してください。
プラグインは、blockly-samples の master ブランチにある gh-pages/index.md ファイルに追加する必要があります。これにより、プラグイン サイトに表示されます。ファーストパーティ プラグインは、テストページを指す必要があります。このページにはサードパーティのプラグインを追加することもできます。プラグインは、ホストされているデモや npm ページなど、所有者が選択したリンクを指すことができます。
公開
最後に、公開します。Blockly チームは、Lerna を使用して、すべてのプラグインのバージョン管理と公開を管理しています。
毎週木曜日に、前回のリリース以降に変更されたプラグインが公開されます。変更を早めに公開する必要がある場合は、プルリクエストにその旨を記載してください。
プラグイン サイトも、プラグインが公開されるたびに更新されます。
公開の準備ができていないプラグインは、package.json で private とマークする必要があります。これは、プラグインが コア Blockly の未公開の変更に依存している場合に発生することがあります。Core Blockly は、各四半期の最終週（3 か月に 1 回）に公開されます。