はじめに
現在自分が活動している趣味コミュニティはあらゆるドキュメントが不足しています。
例えば以下のことが記載されていません。
- 何をしているコミュニティなの?
- どう貢献すればいいの?
- 脆弱性を見つけたときはどうするの?
- サポートを得るにはどうすればいいの?
- どうやって支援できるの?
これらは各リポジトリに個別に書くこともできますが基本的には共通なので使いまわしたいところです。
.githubというリポジトリをOrgに作れば、ドキュメントを全リポジトリで使い回すことができます。
一度書けば
- 明示的に色々なコミュニティマナーを定義できる!
- 新規貢献者さんに読んでほしいことがまとめられる!
- Org内全部に反映される!
- (自分で書けば)別のOrgでも使い回す事もできる!
というメリットがあり、書く価値がありそうに思ったので
現在サポートされているドキュメントを全部書いてみました。
まぁ大規模OSSでもない趣味コミュニティで全てを定義する必要が本当ににあるかというと無いですが
ドキュメントはあるに越したことはないと思うので練習に書いてみました。
できあがるもの
Issue作成時にこのようなガイドを表示させることができます。
現在サポートされているファイル
2022年6月19日現在は下記ファイルがサポートされていました。
ISSUE_TEMPLATE.md
- 概要
- GithubサイトでのIssue作成時に 指定テンプレートを予め入力します
- (もしかしたらVSCodeのGithub拡張機能も対応しているかも)
- 複数作ると、Issue作成前に選択できるようになる
- 書き方が2種類あるようです
- 旧 Markdown型
- 新 Form型(Beta)
- 対応パス
- repo/ISSUE_TEMPLATE.md
- repo/.github/ISSUE_TEMPLATE/*.md
- repo/.github/ISSUE_TEMPLATE.md
PULL_REQUEST_TEMPLATE.md
- 概要
- Githubサイト上でのPullRequest作成時に 特定のテンプレートを予め入力します
- (もしかしたらVSCodeのGithub拡張機能も対応しているかも)
- 複数作ることはできるが、PullRequest作成前に選択画面はでない
- 複数作った場合 プルリクエスト作成ページに
?template=テンプレートファイルというパラメータが要る
- 複数作った場合 プルリクエスト作成ページに
- 対応パス
- repo/PULL_REQUEST_TEMPLATE.md
- repo/.github/PULL_REQUEST_TEMPLATE/*.md
- repo/.github/PULL_REQUEST_TEMPLATE.md
CONTRIBUTING.md
- 概要
- Githubサイト上でのIssue作成時に 右下に貢献ガイドリンクを表示します
- はじめてIssueを立てる際は 強調表示されます
- Githubサイト上でのIssue作成時に 右下に貢献ガイドリンクを表示します
- 対応パス
- repo/CONTRIBUTING.md
- repo/.github/CONTRIBUTING.md
CODE_OF_CONDUCT.md
- 概要
- Githubサイト上 About欄に コントリビューター行動模範を表示します
- 行動模範とは なるべく平穏に争いなくしていきましょうという感じです
- 技術者倫理的なものですね
- 行動模範とは なるべく平穏に争いなくしていきましょうという感じです
- Githubサイト上 About欄に コントリビューター行動模範を表示します
- 対応パス
- repo/CODE_OF_CONDUCT.md
- repo/.github/CONTRIBUTING.md
SECURITY.md
- 概要
- Githubサイト上でのIssue作成時 選択肢にセキュリティポリシーを表示します
- セキュリティポリシーとは 脆弱性発見時 セキュリティ研究者がどう連絡するか等を定義するものです
- Githubサイト上でのIssue作成時 右下にセキュリティガイドラインを表示します
- はじめてIssueを立てる際は 強調表示されます
- Githubサイト上でのIssue作成時 選択肢にセキュリティポリシーを表示します
- 対応パス
- repo/SECURITY.md
- repo/.github/SECURITY.md
FUNDING.md
- 概要
- Githubサイト上 About欄に Sponsor this project エリアを表示します
- Ko-fi、Github Sponsers、任意のリンク(Amazonほしいものリスト等)を指定して表示できます
- Githubサイト上 About欄に Sponsor this project エリアを表示します
- 対応パス
- repo/FUNDING.md
- repo/.github/FUNDING.md
SUPPORT.md
- 概要
- Githubサイト上でのIssue作成時 右下にサポートドキュメントへのリンクを表示します
- はじめてIssueを立てる際は 強調表示されます
- サポートドキュメントとは、どこに連絡するとサポートを得られるかのガイドです
- (開発用リポジトリなのに質問の山が立って困るのを防ぐのに使えそうです)
- Githubサイト上でのIssue作成時 右下にサポートドキュメントへのリンクを表示します
- 対応パス
- repo/SUPPORT.md
- repo/.github/SUPPORT.md
作ってみる
ここからは実際ドキュメントを作ってみます
ISSUE_TEMPLATE.md
ここでは、Issueを作成したときのテンプレートを定義します。私の所属するOrgでは 主に自分が主体で動いているので、自分の思う望ましいIssue というのを考えて定義してみました。下記が揃っているIssueが個人的には望ましいと思っています。
- (人目見てわかる)概要
- (概要を具体的にする)詳細
- (他との関連を示す)関連Issue
- (何をすべきかを示す)参考文献
新機能リクエスト Issue
ほぼ先程の定義通りそのままで作成しました。
---
name: ✨ 新機能 (Feature request)
about: Suggest an enhancement for this project
title: '[FEATURE] <title>'
labels: enhancement
---
### 概要 / Overview
<!-- ツイッターのツイートぐらいの文量で説明 -->
### 機能の詳細 / Feature details
<!-- より細かい機能詳細 -->
### 関連Issue / Related issues
<!-- 既存のIssueと関係あれば そのリンクを -->
### 参考文献 / References
<!-- 実装の参考になるもの アイデア元等 -->
バグレポート Issue
バグレポートは、バグレポートのテンプレートに沿う方が良いかと思います。一般的に必要そうなものを用意しました。
---
name: 🐞 バグ報告 (Bug report)
about: File a bug/issue
title: '[BUG] <title>'
labels: bug
---
### 概要 / Overview
<!-- ツイッターのツイートぐらいの文量で説明 -->
### 現在の挙動 / Current Behavior:
<!-- 何が起こってしまっているか -->
### 起こるべき挙動 / Expected Behavior:
<!-- 期待する挙動はなにか -->
### 再現手順 / Steps To Reproduce:
<!--
例:
1. まず起動して...
2. こういう動作をして...
3. こんなエラーが発生して...
-->
### エラーログ / Error Log:
<!-- もし存在すればエラーログ / Put only if you have -->
### 環境 / Environment:
<!--
例:
- OS: Ubuntu 20.04
- Arch: x86_64
- Node: 16.XX
- Docker: 19.XX
-->
### 関連Issue / Related issues:
<!-- 既存のIssueと関係あれば そのリンクを -->
### 参考文献 / References:
<!-- 修正の参考になるもの アイデア元等 -->
その他
これらは一例で もちろんいろんなやり方があるかと思うので、参考の1つとしてどうぞ。
他にも、DOC、OTHERというのを定義しましたが ほぼ同じなので紹介は省略します。
PULL_REQUEST_TEMPALTE.md
ここではプルリクエストのテンプレートを定義します。書くべきことはIssueとほぼ同じじゃないかと思っているのでIssue Templateと同様にしてみました。
## 概要 / Overview
<!-- どんな内容かざっくり記述 -->
## 詳細 / Details
<!-- 何をしたか細かく記述 -->
## 関連Issue / Related issues
<!-- 既存のIssueのリンクを貼る (もしIssueがなかったら今作ろう) -->
## 参考 / References
<!-- 参考情報/リンク（懸念点や注意点などあれば記載） -->
CONTRIBUTING.md
ここでは、貢献方法についてのガイドラインなどを定義します。かなり長くなるのでざっくり大枠だけですが、下記項目を定義して、それぞれにしてもらいたいことを具体的に書き出してみました。
- 技術者としての貢献
- ユーザーとしての貢献
CODE_OF_CONDUCT.md
ここでは 開発者倫理、行動規範を定義します。かなり長くなるのでざっくり大枠だけですが、下記項目を定義しました。
- 必須の行動
- すべき行動
- すべきでない行動
- モデレータの責任
- 処罰規定
ここは、何を書くべきか本当に何も思いつかなかったので(難しいので)
remarkjs/.github © Titus Wormerからお借りして、箇条書きを意識してアレンジさせていただきました。
SECURITY.md
ここでは セキュリティポリシー、脆弱性発見時の対処を定義します。同様かなり長くなるのでざっくり大枠だけですが、下記項目を定義しました。
- 脆弱性報告の対象
- 脆弱性報告の対象外
- セーフハーバー
- 重大な脆弱性について
- 報告内容
- 報告方法
- 報告のお礼
これも、何を書くべきかぱっと見だと思いつかなかったので(難しいので)
remarkjs/.github © Titus Wormerからお借りして、バグバウンティで見たことある文章を意識してアレンジさせていただきました。
FUNDING.md
ここでは 寄付の方法を定義します。今のところOrg内では寄付プラットフォームを利用していないので、下記のようにAmazon欲しい物リストを登録しました。ただ、これはリポジトリの作成者に関わらず常に表示されます。Amazon欲しい物リストでは、記載された特定個人にしか寄付されないことになるので、人数の多いOrgでは、素直にOrg名義のGithub Sponsers等を用意すべきかと思います。(争いの元になりそうなので...)
custom: ["AMAZON欲しい物リストのリンク", "その2", "その3"]
SUPPORT.md
ここでは 対象のソースコードに関するサポートを受ける方法を定義します。自己流で、下記内容を書いて定義しておきました。
- 会話コミュニティ(Discord)
- コアメンバーの連絡先(Discord)
README.md
もちろん他のリポジトリ同様、.githubリポジトリが何のリポジトリなのか説明を書いてあげるべきです! 今回は下記のような内容を書いてみました。
- リポジトリ内容
- 各ドキュメントリンク
- 参考文献
- ライセンス
profile/README.md
各ユーザーページにプロフィールが設置できるのと同様、Orgでも同様にプロフィールを定義できる仕様があります。profile/README.mdに 下記内容を書いてみました。
- 軽い紹介
- 作っている主要プロジェクト一覧
- 関連リソース(CONTRIBUTION.mdへのリンク)
- ちょっとしたネタ (Fun facts)
- コアメンバー
- 開発言語
- コミュニティリンク
やってみて気づいた仕様
.githubリポジトリはなにやら若干よくわからない仕様があるようなのでメモしておきます
今開いているブランチに対応するブランチが .githubリポジトリから読み込まれる...?
例えば デフォルトブランチがdevelopになっているリポジトリがある場合、 .githubリポジトリにも developブランチがないと ISSUE_TEMPLATEが反映されません。確かに.githubがブランチ毎に別で定義されていたら、その挙動であるべきですが、該当ブランチがなければデフォルトにフォールバックしてほしい...
フォルダパスの挙動が謎
ISSUE_TEMPLATEは .githubリポジトリの中に .githubフォルダを作ってそちらに格納しないと、各リポジトリで認識されません。.githubリポジトリ直下が各リポジトリの直下に直接統合されるイメージ?で動くのかもしれないです。また、profileも少々不思議なパス探索をするため、相対パスはなるべく使わないほうがよさそうです。
やってみた感想
ここまでのドキュメントを書くの結構しんどかったですが、書いた甲斐はありそうに思います、人に言うつもりで自分もこうあるべきだよなというのを認識できた気がします。あとはこれを書く中で、自己的なエンジニア価値観というか、こうあってほしいというのを文章化できたというか、そんなマインド的な何かを感じました。今回書いたこれらドキュメント通り、うまく各開発を回せるようにしたいです。
参考