アクションを自作するときに README に書くべき情報 [GitHub Actions]
概要
アクションを自作するときに README に何を書くべきか迷うと思います。
作る側としては Usage だけ書いておけば分かるだろうと思ったりするのですが、使う側からするともう少し情報が欲しいと思うことがあったりします。
なので必要だと思われる情報をリストアップしました。
アクションによっては不要なものもあるかと思いますので、その場合は省略してしまってください。
使い方 (Usage)
実際にどう使うのかのサンプルコードです。
これがあるとコピー＆ペーストできますし使うイメージが湧きやすいです。
Example workflow として全体のワークフローを貼ってあるアクションもありますが、どこを見たらいいか分かりづらくなってしまうので Usage では uses の部分をピックアップするのが良いかと思います。
環境変数、入出力 (Environment variables, Inputs, Outputs)
action.yml を見れば分かる情報だったりするのですが README に書いてあると親切です。
表にすると見やすいです。
Description が長くなりそうだったら Detailed inputs など別途項目を設けてもいいかもしれません。[1]
サポートしているランナーやイベント (Supported)
書いてあるのをほとんど見かけないのですが Ubuntu では動くけど Windows では動かなかったり（特に Docker container アクション！）、特定のイベントのペイロードから情報を取得していたりすることもあると思うので明記しておいた方がいいと思います。
サポートしているランナーのテストを書いてバッジも貼っておくと完璧です。
依存関係 (Dependencies / Required)
こちらも書いてあるのをほとんど見かけませんが記載しておいた方が良さそうです。
特にセルフホストランナーでは自分でインストールしないといけないので手探りは大変です。
ライセンス表記にも関わってきます。
必須バージョンがある場合は併せて書いておきましょう。
貢献 (Contributing)
開発を手伝ってくれる方へ向けて Issue や PR を作る際の指針などを CONTRIBUTING ファイルに書いてリンクしておくと良さそうです。
ライセンス (License)
右上の About に表示されるようになったので LICENSE ファイルを用意するだけでいいと思いますが、書きたい方は書いても良さそうです。
新機能、破壊的変更 (What's new, Breaking changes)
メジャーバージョンアップのときは最初の方に書いておくと良さそうです。
パーミッション (Recommended permissions)
あまり把握していないので参考として actions/stale のリンクだけ貼っておきます。
README.ja.md
多くの方に使ってもらうためには README.md は英語で書きましょう。
日本語でも書きたい方は別途ファイルを用意すると良さそうです。
最後に
以前作成した Composite アクションテンプレート に反映してあります。
Composite アクションを作成しようと思っている方は良かったら使ってください。
JavaScript アクションや Docker container アクションを作る方は README だけコピーしていただいても構いません。
-
参考: actions/stale ↩︎
Discussion