10日目:RCCを支える総会文書執筆環境その2

2016年12月10日

4回生の@ABCanG1015です。今年で卒業です。

2年前に@bitter_fox先輩が「RCCを支える総会文書執筆環境」という記事をアドカレで書いていたので、あれから2年経った今の総会文書執筆環境について書こうと思います。先に2年前の記事を読むことをオススメしますが、ざっくり3行で言うとこんな感じです。

TexをDropboxで共有してて地獄だった
GitとBitbucket、Jenkinsを導入した
プルリクでレビューできるし、マージされるとpdfがビルドされて最高！

新たな問題

しかしながら、GitやLatexに慣れない会員も多く、めちゃくちゃスムーズになったわけでもありませんでした。

Texのコマンドが間違っていてビルドが通らない
プルリクのコンフリクト地獄

Texのコマンド名をタイポや、「&」などの文字のエスケープ忘れなどによりビルドが通らないことがしばしばありました。手元でビルドチェックしてくれる人は多くなかった気がします(Windows向けにビルドスクリプトを書いてなかったのも良くなかったかもですが)。また、総会文書では担当ごとにファイルを分割して執筆しますが、最終的にはそのファイルを読み込むために、統合用のファイルに\inputコマンドを記述します。そのため、統合用のファイルがコンフリクトしてしまうということが多々ありました。

今までは、これを知識のある人が手動でいい感じにやってきました。プルリクが作成されると、その人がブランチをpullしてきて手元でビルドして、ビルドに失敗するとコメントします。また、プルリクがコンフリクトしている時は、マージする時にその人が手動で行います。しかし、その人ももう卒業です。ということで、このいい感じにする仕事を自動でできるようにしました。

WerckerやBitbucket PipelineによるCI
テンプレートの生成ツール

WerckerやBitbucket PipelineによるCI

2年前は一応Jenkinsを使っていましたが、developブランチに対してしか動かしていませんでした。今ではWerckerやBitbucket Pipelineを導入して、全コミットに対して実行しています。ビルドが失敗するとBitbucketから見れるようになっています。

また、RCCではRCC製の文章体裁チェックツールである「ta9boh」も実行するようにして、テスト環境も整えました。しかしながら、テストに失敗してもプルリクの画面から直接エラー内容を見ることができません。さらにWerckerの場合だと、エラーを見るページも一部の人しか見ることができません。これを解決するために、Bitbucketのプルリクにコメントを送信するツールを作りました。

ABCanG/bitbucket_pr_comment

BitbucketのOAuthアプリケーションを登録して、そのキーとコメントしたい内容を指定してこのツールを実行します。このツールは、gitコマンドを使ってブランチを特定し、BitbucketのAPIを使って該当するプルリクの特定やコメントの送信を行います。このアプリをテストスクリプトに組み込むことで、テスト時の内容をプルリクのコメントとして出力できるようになります。

これで文章体裁チェックツールの出力結果も、しっかりコメントされます(以前は手動で実行して、出力結果を貼り付けるという作業が必要で辛かった)。文章体裁の指摘はプログラムがやってくれるようになったので、特定の人対してのヘイトが溜まらなくていいですね。

さて、文章体裁はいいとして、Texのビルドエラーはどうしてるの？と思った人がいるでしょうか。むしろ大事なのはこっちですよね。Texのビルドエラーはログファイルに出力されますが、少し読みにくいです。そのため、ログファイルを読みやすくしてくれるスクリプトを作りました。

いい感じにlatexのログからエラーを抽出するやつ

総会文書はファイルが分割されてinputコマンドによって読み込まれています。inputコマンドでは「./」から始まる相対パスで読み込むようにしています。また、エラーの文章は「!」から始まるため、これらを正規表現で探して、エラー文のみを抽出しています。

テンプレートの生成ツール

もう一つはコンフリクト対策ですね。テンプレートを作成して、事前にinputコマンドを記述したファイルを作ることでコンフリクト対策をしようとしました。事前に章のタイトルや担当者を記入したymlファイルを作成してツールを実行するとテンプレートファイルが作成されます。これで最初からファイルが用意されるため、各担当者が編集するべきファイルが明確になり、inputコマンドを記述する必要もないためコンフリクトの発生を防げると思いました。

しかし、実際に使ってみるとうまく機能しませんでした。リポジトリのセットアップ時にテンプレートを作成していましたが、あとからファイルの追加とinputコマンドを記述するファイルの変更が行われて、結局コンフリクトが発生してしまっていました。そこで、現在ではinputコマンドを記述するファイルをmakeコマンド実行時に自動生成するように変更しています。指定されたディレクトリ内にtexファイルを生成するだけで勝手に読み込まれるようになります。この変更を行った後に総会文書は作成されていないので、次の総会文書執筆時にどうなるかが非常に楽しみです。これで今度こそコンフリクトに悩まなくて良くなるはずです。