読み飛ばしてください
おはようございます、しなもんです。
OSS開発をたくさんやる中で、明確にしときたい規則ってありますよね。
コミットメッセージやコーディングルールなどです。
他にも、新しい開発者のためにセットアップの方法なども書いてあるべきです。
そんなところで、先日とあるOSSであるものを見かけました。「DEVELOPERS.md」です。
つまり「開発者向け情報」が書かれたmdファイルです。
これを読んでいるとファイルの必要性をかなり感じたので、
分析しつつ自分なりに書いてみて、あわよくば普及していければと思います。
とりあえず分析してみた
今回参考にしてみるファイル
Angularとは、Google主導で開発がされているOSSなJavascriptフレームワークです。
さっそく読んでみます。
1. 目次
目次が記述されています。リンクが付いていて飛びやすくなっています。助かります。
・Development Setup
・Running Tests
・Coding Rules
・Commit Message Guidelines
・Writing Documentation
2. Development Setup
開発セットアップについて記述されています。
git,node,yarn,gruntといった様々な方法で開発環境をセットアップする方法について説明しています。
依存関係のインストール、リポジトリのフォーク、ビルド、開発サーバーの実行について書いています。
3. Running Tests
テスト方法が記述されています。
コンソールをポチポチするだけでテストが回るようにたくさん書いてくれています。
4. Coding Rules
まず、階層についてや文字数、テストの規則について記述されています。
一般ルールとGoogleのJavaScriptスタイルガイドのルール（例外あり）の二つから構成されています。
・コードは1行100文字を超えないようにする
・すべての機能やバグ修正は、1つ以上のテスト（specs）を使ってテストする必要がある
などがあります。
5. Git Commit Guidelines
Gitのコミットメッセージのフォーマットに関するガイドラインを説明しています。
プロジェクトの履歴を見やすくし、変更ログを生成するためにいろいろ書いています。
コミットの種類についての明確化や、サブジェクトについての説明があります。
・命令形、現在形を使用する（例："change"）
・最初の文字を大文字にしない
・最後にドット（.）をつけない
この辺は私もよく迷うというか多分混ざってしまっているので、明確になっていると助かります。
6. Writing Documentation
AngularJSプロジェクトで使用されているjsdocの概要について説明されています。
ブロックタグの紹介や独自のタグ、一般的なマークダウンの規則などがあります。
jsdocというのは、VSCodeとかで便利な奴です。
調査まとめ
開発者がプロジェクトに貢献するまでの流れに必要なことがたくさん書いてあるという印象です。
こういうのがあると、新規開発者が増えそうですし、書いている自らもルールが分かりやすくなってコードを書きやすくなる気がします。
では私も書いてみます。
実際に書いてみる
調査したファイルを踏襲して書いてみます。
1. 目次
目次を書きます。
以下のようにすると見出しに飛べるようになります。
* [見出し](#見出し名)
## <a name="見出し名"> 見出し
2. Development Setup
今回書いているのはDockerで簡単に起動できるものなので、適当にその旨を記述します。
0から起動するところまでを書いていきます。
3. Running Tests
テストの項目は省略します。
（テストする規則が整っていなかったので）
4. Coding Rules
規則を書きました。
pep8を引用することで規約を明確にしています。
5. Git Commit Guidelines
angular.js/DEVELOPERS.mdを参考に書いてみました。
6. Writing Documentation
ほとんどをCoding Rulesに記述してしまったので省略します。
まとめ
Developers.mdを書きました。
開発者にやさしいリポジトリっていいですよね。多分。
OSSでたまに見かけるガイドラインですが、さらに普及すればいいなと思いました。
ちなみに、今回書いたものはここにあります
是非参考にして書いてみてください...！
参考