GitHubを使った開発パターン的なのを妄想している

プロジェクトの状況にもよるんだけど、ドキュメントがなかったり、管理側の知識がなかったり、経験値が少ない人が多かったり色々ある。
コードがドキュメントで動けるプロジェクトだといいんだけど、現実はそうは行かない。


最近はGitHubを使った開発が多くなってきたので、GitHubを前提にした開発方針でもいいんじゃねと最近は思っている。
Gitlabを使っているとか色々なパターンとか色々あるけどまあそこは誤差としておく。
ともかく最近はGitHubでの開発パターンというか開発スタイルというかを考えていて、WIPとか個別での手法はあるんだけど全体としてまとまっている情報って見たことがなくて、もやもやしていてまとめてみる。

ちなみに、RailsでのWeb系を前提に書くけど分野関係なく通用するはず

基本方針

できるだけ楽をする方向で。
ただし、目の前の楽だけを追えば死ぬので、技術的負債を意識すること。

ブランチ

git-flow,git-hubflow等なんでも良いけど、ブランチの運用方法の方針を決定したほうが良い。
できればツールを使った方が楽。

WIP開発

WIP開発を採用する。
将来もっと良いのが出てくれば変更しても良いけど。


WIPなので当然コードレビューも入る。
ある程度チーム全員でコードレビューをして、全員がまんべんなく知識を共有している状態なのが望ましいと思う。

ドキュメント

ドキュメントをgitで管理する意義

ドキュメント(固い言い方をすれば仕様書)はできるだけGitHub上にMarkDown形式で保存しておく。


ドキュメントの役割は色々あるけど、なんとなくこのあたり

  • 将来作るべきモノの管理
  • とある時点での全体を俯瞰して確認できること(本来あるべき形と現状の姿)
  • 無駄なコミュニケーションの排除
  • 引き継ぎとかその他色々


思い返してみるとドキュメントって固いプロジェクトだと当然あるけど、そういった現場でもソースコードとドキュメントの同期、履歴管理ってほぼ出来ていなかったように思う。
そこでgitでソースコードとドキュメントを同時に管理すれば上記問題はほぼ解決するはず。
MarkDownなので文法は簡単だし、grepでもなんでも好きに検索もできるはず。

手動ドキュメント

多分2種類あるはず。

  • 本来あるべき姿を書いたもの(いわゆる仕様書)
  • 環境構築、コーディング規約とかの開発のヘルプ的なもの


どう転んでも手動で書かざるをえないので書くしか無い。
ただ、頑張り過ぎても管理が大変なので重要な部分の考え方とかその辺りだけにしておいたほうが無難。
最近だとドキュメントを書く事自体が嫌なのか用意しない場合が多いので、一度書いたらほぼ更新する必要がないように


あと、Changelogはあったほうが良いかも。
gitで特定の過去に戻れてもその時点での全体で何を作ったかを簡単に把握するのは多分難しい。
極端な例をだすとLinux Kernelとかgitで戻ってもChangelog見ないと何を目的の修正かまず理解できないと思う。


ただ、テストコードと同じで時間はそれなりに使うしメンテナンスも必要なので、時間を見て重要そうな部分から始めれば良い。
MarkDownだと単なるテキストなので、某Office的なソフトを使うよりもデザインを気にせずに作成できるはずなのでさほど時間はかからないはず。

自動化ドキュメント

現状の姿をドキュメントにまとめる必要がある。
ただこの辺りって昔から自動化の方向で来たので、その流れに従って自動化しておいたほうが良い。
最悪見る人が少なくても無いよりよほどマシ。


ソースコード
YARDとかJavaDocとかその辺り。
コメントでドキュメントを書くので、出力するドキュメントを見なくてもエンジニアだとコードを読む場合でも理解しやすい。
ただ、こういったツールはHTMLで出力するパターンが多いのでgithub上だと確認しづらいのが難点。
そもそもhtml+cssで表示する内容とデザインを分けたという歴史があるのに、なぜわざわざドキュメントをhtmlで出力するのかがよくわからない。
表示を整えたければ、テキストに出力してからHTMLやpdfに出力するという方向で良いのに...


RMDB
Webアプリだと多分いちばん重要(な気がする)。引き継ぎをきちんとしていないと、このテーブルのこのカラムの使い方がわからないとか色々でてくる。
Rails + gemだとrails-erd, schemadocあたりが良い。ER図(pdf)の作成、スキーマをjsonで吐き出してくれる。
annotateを使えば、スキーマをmodelの先頭に追加してくれる。
ただ、schemadoc,annotateはスキーマを吐き出してくれるだけで意味がわからない。ER図は必要だけど意味までは理解できない。
ということで、migration_commentsでDBに直接テーブルコメント、カラムコメントを追加している。
ちょっとしたスクリプトを作れば、スキーマとそれぞれのコメントをドキュメントに出力するのは簡単だ(良いgemがあれば良いのだが知らない)。


WebAPI
autodocというgemがある。
https://github.com/r7kamura/autodoc を見ればわかるが、specを書けばAPIのドキュメントをMarkDownで生成してくれる。
すばらしい。


上記以外のデータストア
KVSなりSolrなり何でもよいが、このあたりは対応方法を思いついていない。
今後の課題だ。


ドキュメントの翻訳
OSSで昔からあるほうにhoge.ja.md、hoge.en.mdとかにしておけばよい。

自動化

もう一般的だけどjenkins使えばgithubとの連携が出来る。
使わない手はないはず。設定が面倒だけど...
ドキュメントの自動生成、spec、デプロイ、lint、rubocop、bugspots、セキュリティチェックとか色々できるはず。

テストが書けない or 書きづらい分野とかはまだまだあるので、そういった部分はどうするのが良いんでしょうね。
Webだとデザイン崩れとか、組み込みだとハード前提なので色々厳しいとか。

開発タスク管理

waffle.ioとかを使えばgithubと連携して開発タスクの管理ができる。
なんでも良いけどこういったツール、サービスを使ってgithubとの連携をするべきだろう。

インフラ周り

最近はchefのようなツールがだいぶ一般化してきている。
インフラもgitで管理できるのでこの方向で頑張ったほうが良いはず。




他にも色々要望があるかも。
できれば面倒な事は自動化して、何回も同じ事をする場合はドキュメントなりプログラム化するなりすれば無駄が省けるはず。