16日目: RCCを支える総会文書執筆環境

2014年12月16日

執行委員長の@bitter_foxです．
最近は研究室が快適すぎてあまり部室に行けてないです．
他のB3も部室に行けていないのかなぁと思っていたのですが，たまに部室に行くと何故かB3が大量に居てびっくりしました．
どうやら研究室課題からの現実逃避をしている者が何人か居るようです．大変そうです．

さて，RCCでは年に2回，総会を開いています．
総会がどういうものかは2014年度第一回RCC総会を行いました！を見てください．

RCCの総会では議案書を事前に作成して総会に提出して議決を受けるという形を取ります．

この議案書の作成が一年前まで，大変な作業だったのです．まぁ，今でも大変な作業なのですが，不毛な作業をたくさん行っていました．
議案書はTeXで書いているのですが，皆がバラバラで書いていて，それをDropboxで共有して，最後に誰かが統一をしてビルドしていました．
そのためどこかでコマンドが間違っていると，最後の最後にエラーが大量に出てそれの修正で1日かかるなどしていました．
しかも，レビューするための仕組みは無く，最後の最後までほとんど行われていない状況でした．

いかにしてこのひどい文章執筆環境を改善させていったのか
次の5つの技術・サービスから紹介します．

TeX
Git
Bitbucket
Makefile
Jenkins

TeX
議案書はTeXで書いているのですが，テンプレが多数存在していて，それを共通して皆が使えるようにいくつかコマンドを定義しました．例えば，文責は今までは「\begin{flushright}文責：一回生　立命太郎\end{flushright}」と書いていました．
共通化できる部分が多かったので，「\writtenBy{一回生}{立命}{太郎}」と書くだけで上のように展開されるようにしました．また，「一回生」は人によって「1回生」や「１回生」などと書いてしまうこともあり，共通化したかったのでこれも「\firstGrade」というコマンドにしました．
結果的に先ほどの文責は「\writtenBy{\firstGrade}{立命}{太郎}」と言う風に書けるようにして，どのような表記がされるかは意識しなくても良いようにしました．また，よくあるテンプレも極力書かなくて済むようにしました．
例えば，文章のタイトルは

2014年度第1回RCC総会
議案書

となるのですが，これを以下のようにより宣言的に書けるようにしました．

\year{2014}
\zenki
\titles

Git

今まではDropboxで共有していたので，コンフリクトが起きると大量の(誰々の競合コピー)ファイルが生成されてしまっていました．
また，どれが最新なのか，どれが更新されたのかがわからない状況が生まれていました．
そこでバージョン管理ソフトウェアとしてGitを導入しました．Gitのブランチ運用としてはA successful Git branching modelを踏襲して運用しています．
各自でブランチを作って執筆していき，完成したらdevelopにマージして，一段落ついたらdevelopからreleaseブランチを作り最終調整をして，masterにマージされて完成という流れです．
コミットグラフが綺麗に伸びていき，収束していくのを見るのはいつもいい気分です．おかげで会員にとってはGitを実践的に勉強するいい機会になりました．(無理やり使わせたら案外使えるようになるもんです．もちろん勉強会してるんですけどね)総会文書にはRCC規約も含めるのですが，RCC規約も別のGitリポジトリで管理していて，それをsubmoduleとして含めるようにしています．

BitbucketGitリポジトリのホスト先としてBitbucketを使用しています．
Bitbucketは無料アカウントでprivateリポジトリが無制限に作れるという特徴があります．
また，大学のメールアドレス(xxx.ac.jpなど)で登録するとコラボレータ(リポジトリごとに設定できるプッシュ権限を持ったユーザ．無料アカウントなら最初は5ユーザまでだったかと思います)が無制限になる(最上位料金プランと同じ)という特典があります．
RCCではチームアカウントを大学のメールアドレスで登録して，そこのチームに各会員を放り込んでいます．
Bitbucket最高！！！Bitbucketではイシュー駆動で執筆を行っています．
執筆部分ごとにイシューを作り，執筆をしてそのイシューを潰していきます．
また，それ以外の普通のイシュー(誤字とか)もイシューとして登録をして，それを解決していく事で執筆を進めています．
こうすることで，何が終わっていなくて，今どんな問題が残っているのかが一目瞭然になりました．また，developへのマージは全てプルリクを通して行います．
こうすることで，絶対に誰かのレビューが入り，誤字脱字等の問題やわかりにくい表現を潰す事が出来ました．
ちなみに，前回の総会文書執筆の最中にBitbucketのプルリクにタスク機能が搭載されました．
コメントに対してタスクを作成することができて，完了したタスクと未完了のタスクが分かりやすくなりました．
タスクというのはプルリク内での小さなイシューなどがあたります．
このタスク機能も早速使っていき，より一層効率的にレビューができるようになりました．(ただし，皆がレビューしてくれるとは言っていない)
Bitbucket最高！！！

Makefile
いちいちplatexとかってコマンドを叩くのが面倒くさいのでMakefileを作ってあります．
基本的にはmakeを叩くだけで全ての作業が済むようになっています．
RCC規約のリポジトリを取ってくるのもMakefileにやらせています．(git submodule updateとか)ビルドしたかったらgit cloneしてmakeを叩くだけです，最高！！！

Jenkins
最後は頼もしいJenkinsおじさんです．

Jenkinsおじさんというのは継続的インテグレーションツールの一種でビルドとかテストとかを勝手にやってくれるありがたいおじさんです．RCCでは学内のRCCのサーバでJenkinsおじさんを飼っていまして，このJenkinsおじさんに仕事をしてもらうように設定しました．
5分おきにリポジトリを見張って，新しいコミットがあればビルドするように設定してあります．