背景

自動配線プログラムFreeroutingのリポジトリを確認するとKiCadのプラグインとしてメニューからインストールする方法が追加されているのを発見しました。
KiCad公式機能ではないFreeroutingが登録されてているなら自分が作ったプラグインも登録できるだろうと試したところ登録できました。

備忘録として対応内容を記事に残します。

使ったもの

gitlabのアカウント
アドオンのmetadata管理リポジトリはgitlabにあるので、それにmerge requestするためにアカウントが必要です。
ちなみにKiCadにおけるアドオンはプラグインとライブラリを意味します。
プラグインを公開しているリポジトリ
プラグインのzipファイルをダウンロードできるurlが作れれば良いので、こちらはgithubでもgitlabでも良いです。
この記事ではgerber_to_orderをKiCadのアドオン一覧に登録しました。

アドオン一覧へ登録のために自作プラグインのzipファイルを準備

KiCad AddonsのPython pluginsで要求される通り、プラグインの公開には下記の構成のフォルダとファイルを含むzipファイルの生成が必要です。
（なお、ライブラリはプラグインとは異なるファイル構成を要求されるのでKiCad AddonsのContent librariesを見てください。）

zip file
|- plugins
   |- __init__.py
   |- ...
|- resources
   |- icon.png
|- metadata.json

それぞれ解説します。

zipに含めるmetadata.jsonは、download_sha256などダウンロードに必要な情報や、そのzipのバージョン以外の情報は不要

KiCad Addonsの説明では全ての情報が記載されたmeatadata.jsonが例として表示されおり、donload_sha256の扱いをどうしたら良いか戸惑いましたが下記のjsonで十分でした。
versionsは配列ですが、改版してもzipに含める情報はそのzipが保持するコードのバージョンのみでよく、download_*系の情報は不要でした。

metadata.json（zipに含めるもの）

{
    "$schema": "https://go.kicad.org/pcm/schemas/v1",
    "name": "gerber to order",
    "description": "Create gerber files for some PCB order services.",
    "description_full": "Create zip files which includes gerber files for each PCB services.",
    "identifier": "com.github.asukiaaa.gerber-to-order",
    "type": "plugin",
    "author": {
        "name": "Asuki Kono",
        "contact": {
            "web": "https://asukiaaa.blogspot.com"
        }
    },
    "license": "MIT",
    "resources": {
        "homepage": "https://asukiaaa/gerber_to_order"
    },
    "versions": [
        {
            "version": "1.0.0",
            "status": "stable",
            "kicad_version": "6.0"
        }
    ]
}

自分が作ったzipに含めるmetadata.jsonはリポジトリで公開しています。
https://github.com/asukiaaa/gerber_to_order/blob/master/metadata.json

指定されていないファイル以外をzipに含めるとエラーになるので、zip作成は自分で実施

pluginsの中には複数のファイルの配置が許容されていますが、それ以外の余分なファイルが配置されていると後のmerge request作成時にエラーが発生するので注意です。
自分がプラグイン公開に取り組んだ時はREADME.mdを含むzipファイルではエラーになりました。

README.mdを置かないリポジトリならgithubのリリースでzipファイルを使ってもエラーになりませんがリポジトリを覗いた時にREADME無しで説明が無い状態を自分は避けたいです。

github actionsで対応する場合

githubのリリース処理とバージョンを合わせたい場合github actionsの利用が便利です。
下記の記事で設定方法を解説しています。

github actionsでrelease時にzipファイルを生成して関連情報をreleaseの本文（body）に表示

github actions実行のために配置したファイルはこちらです。

https://github.com/asukiaaa/gerber_to_order/blob/master/.github/workflows/create-archive.yml

手動で対応する場合

linuxの場合は下記のコマンドで欲しいzipファイルを作れました。

zip kicad-addon metadata.json -r plugins -r resources

上記コマンドで生成したkicad-addon.zipをどこかに置いてダウンロード可能な状態にします。
githubのリリースページにアップロードするのが一手です。

下記のリリースページのzipファイルはgithub actionsで生成していますが、手動でも置けます。

https://github.com/asukiaaa/gerber_to_order/releases/tag/1.0.1

KiCadのアドオンのmetadataリポジトリに対してmerge request

プラグインのzipをダウンロード可能な状態にしたら、それの情報をKiCadのリポジトリに登録します。
KiCad AddonsのSubmitting your packageが該当する説明箇所ですが、具体例が載ってないのでアドオンのmetadata管理リポジトリの他のアドオン（プラグインやライブラリ）を参考にしつつ作成します。

merge request先リポジトリはこちらです。
https://gitlab.com/kicad/addons

自分が作成したmerge requestはこちらです。
初回: Add plugin gerber_to_order
改版時: Add information version 1.0.1 of gerber_to_order

上記のmerge requestでは自分のアドオン（今回はプラグイン）を配置しているurlに合わせてフォルダを作成（packages/com.github.asukiaaa.gerber-to-order）し、アイコンファイルとmetadata.jsonファイルを配置しました。

metadata repository
|- packages
    |- com.github.asukiaaa.gerber-to-order
        |- icon.png
        |- metadata.json

フォルダ名にアンダースコア「_」は使えない（自動確認でエラーになる）ので、ケバブケース（「-」繋ぎ）やキャメルケース（単語の区切りを大文字にする）で対応してください。

アイコンファイルは64x64ピクセルの画像です。
これがKiCadのアドオンマネージャに表示されます

KiCadのmetadataリポジトリに配置するmetadata.jsonは、zipファイルに配置したmetadata.jsonに下記の情報を追加したものです。

versions download_url
versions download_size
versions download_sha256
versions install_size
過去に公開したバージョンがあるなら、それの情報

上記の情報はaddonsリポジトリのpacking toolkitを使えば把握できるようです。
自分はgithub actionsに任せて上記の情報はgithubのリリースコメントで取得できるようにしました。

icon.pngとmetadata.jsonを該当するフォルダに配置してmerge requestを出したら自動確認処理が動きます。

エラーになった場合はエラー内容を読み、基本的にエラーが無くなるまで修正してください。

例外として、過去のバージョンの設定変更（kicad_version_maxを指定していなかったものの追加したい場合など）を含むmerge requestに対するvalidate pushに関するエラーは、過去のバージョンの設定変更はバージョンの識別子（多分1.0.0などの文字列）の削除や変更以外は行えるようなので、人による確認を待って良いです。
それに関するKiCadの中の人の応答はこちらです: https://gitlab.com/kicad/addons/metadata/-/merge_requests/208#note_1380745367

zipに含めるmetadata.jsonとKiCadのmetadataリポジトリに登録するmetadata.jsonの内容は似ているものの1つのファイルで管理するのは困難と自分は判断して別々のファイルで管理しています。
asukiaaa/gerber_to_order/metadata.json
gerber_to_order/docs/metadata.json

自動確認処理を成功させたらmerge requestへの応答を待ちます。

merge requestを作成してから反映されるまでの待ち時間: 10日前後

merge requestは過去の取り込みを見ると週1回金曜日に対応される傾向にありますが、自分が行った2回のmerge requestどちらも7日以上mergeされなかったので催促しました。
1週間以上放置された上で催促すると数日で対応してくれる傾向にあるので、放置されていると思ったら催促をお勧めします。

自分がした催促
https://gitlab.com/kicad/addons/metadata/-/merge_requests/205#note_1352861621
https://gitlab.com/kicad/addons/metadata/-/merge_requests/208#note_1363110024

人によるmerge request受理が行われても即反映ではなく、その後botが管理するpackage repositoryに情報が取り込まれたらKiCadのアドオンマネージャでダウンロード可能になります。
botの取り込みはmerge request受理後の日本時間20時に行われます。

自分の場合のmerge request取り込み準備完了からKiCadのアドオンマネージャに反映されるまでの経過はこちらです。
反映まで半月ほどかかると思って気長に応答を待つのが良いです。

初回登録時:
merge request自動確認全て通過: 2023.04.09 23:12+0900
9日後
merge request受理: 2023.04.18 12:34+0900
7.5時間後（日本時間20時）
ボットの取り込み: 2023.04.18 20:01+0900

1.0.1への更新:
merge request自動確認全て通過: 2023.04.22 20:01+0900
14日後
merge request受理: 2023.05.06 10:25+0900
9.5時間後（日本時間20時）
ボットによる取り込み: 2023.05.07 20:02+0900

ボットによって取り込まれたら、プラグインコンテンツマネージャ（なぜアドオンマネージャでないのだ）に表示されます。

記事を書いている時点ではプラグインの表示順は登録や更新の日時が新しいものが下になるようです。
仕組みが長く続くと保守されなくなったプラグインが上に表示されて良くない気がしますが、そのうちアルファベット順に変わるでしょう。

おわり

KiCadプラグイン配布用のzipファイルを作成してダウンロード可能にしてKiCadのアドオン管理リポジトリにmerge requestして受理されたことで、KiCadのプラグインマネージャから作ったプラグインがダウンロード可能になりました。

期待通りに設定できて良かったです。
自分が必要だと思う情報を記事に残したつもりですが「載ってなかったけどこの情報が欲しかった」などがありましたら、記事に情報を追加しますのでコメントしていただけると嬉しいです。

参考

KiCad公式の説明ページです。
KiCad Addons

今回公開したKiCadプラグインです。
gerber_to_order

github actions利用の参考記事です。
github actionsでrelease時にzipファイルを生成して関連情報をreleaseの本文（body）に表示

merge request対象のリポジトリです。
https://gitlab.com/kicad/addons/metadata

自分が作成したmerge requestです。
初回: Add plugin gerber_to_order
改版時: Add information version 1.0.1 of gerber_to_order

試行錯誤な日々

ページ

2023年5月15日月曜日

自作したKiCadのプラグインを公式の一覧に登録

背景