このドキュメントでは、新しいプラグインを作成する方法について説明します。説明されているプロセスはファーストパーティ プラグインの作成を対象としていますが、サードパーティ プラグインの作成のガイドラインとして使用できます。
プラグインの概要については、プラグインをご覧ください。
プラグインの作成の概要については、プラグインの作成方法（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。
- スクリーンショット、GIF、またはモックアップ（プラグインに UI 機能が含まれている場合）。
- サードパーティ製プラグインではなくファーストパーティ製プラグインであるべき理由。
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 回）に公開されます。