論文のバージョン管理とCI
皆さんこんにちは,ちゃんと論文書いていますか?もしかするとすでに書き終わっている方もいると思いますが,私は絶賛執筆中というか筆が全然進まなくて困っています.
こんな記事を書いている場合ではない
「論文(だけじゃなくて形あるもの)はちゃんとバックアップをとっておけ!」と教員や先輩に口を酸っぱくして言われていると思います.実際バックアップを取っておいて損することはないですし絶対取っておいたほうが良いです(複数の環境にバックアップは起きましょう). いつ何時データが飛ぶかわかりません.私もつい先日,7年間ほどお世話になったPCの電源がつかなくなりました...
それはさておき複数の版を管理する場合,次のようにファイル名を変えて異なるバージョンを保存していく事があるかと思いますが,最終的にどれが"本当の"最終Verなのか分かりません.
卒論.tex 卒論_1.tex 卒論修正版.tex 卒論修正版(1).tex 卒論_先生コメント.tex 卒論最終.tex 卒論rev.tex 卒論_図rev.tex sotsuron_final.tex sotsuron.tex thesis.tex
このような問題を解決する方法として,バージョン管理システムを使う方法があります.
また,最近はWordやGoogle document自体に版を管理する方法があるようですがTeXファイルなどのテキストファイルの版を管理するにはやはりバージョン管理システムを使うほかありません.
バージョン管理システムと検索すると大体SubversionかGitが出てくると思いますが,近年の流れとしてGitを使うのが主流です.正直個人で利用する分にはどちらでも問題ないです.
バージョン管理システムを導入することにより論文のバージョンをいい感じに管理することができましたが,まだバックアップは取れていません.
しかし,先に述べたバージョン管理システムはGithubやBitbucketなどのソースコードホスティングサービスを使用することができ,そこにアップロード(Push)しておくことでバックアップを取る事ができます.
ここで特に気をつけなければならないのは,GithubやBitbucketなどのリポジトリをPrivateにしておくことです.Publicにしてしまうと第三者が自由に見ることができてしまいます.
またGithubやBitbucketにはCI(Continuous Integration, 継続的インテグレーション)のための機能が含まれており,何らかのイベント(例えばコードの変更)のタイミングで指定したアクションを実行できます.
これを使うと新しく変更を加えPushしたタイミングでTeXファイルをコンパイルし,生成されたPDFをアップロードする事ができます.
メリットとしては,
- ローカルにコンパイルする環境がなくても良い(環境に依存しない)
- コンパイルに失敗する変更が特定できる
- バージョンとそれに対応するPDFが保存される
等があると思います.
CIの設定
ここでは,GithubとBitbucketでの設定方法を述べます.
まず双方に共通するのがLaTeXのコンパイル設定を記してある以下のファイルです.
ファイル名は.latexmkrc
としてリポジトリの直下に置いておきます.
#!/usr/bin/env perl $pdf_mode = 3; $latex = 'platex -halt-on-error'; $latex_silent = 'platex -halt-on-error -interaction=batchmode'; $bibtex = 'pbibtex'; $dvipdf = 'dvipdfmx %O -o %D %S'; $makeindex = 'mendex %O -o %D %S';
Github/Bitbucketともにpaperist/alpine-texlive-jaという公開されているDocker imageを使用させていただいています. それぞれの設定方法は以下に示します.
Github
Github用の設定です.
GithubではGithub Actionsという機能を使うのですが./github/workflow/
というディレクトリに設定ファイルを置くと利用できます.
ここでは次にようにmain.yml
ファイルを作成し,上記ディレクトリに配置します.
name: Build on: [push] jobs: build: runs-on: ubuntu-18.04 steps: - uses: actions/checkout@v1 - name: Build latex file uses: docker://paperist/alpine-texlive-ja with: args: latexmk index.tex - uses: actions/upload-artifact@v1 with: name: index.pdf path: index.pdf
これをcommitしてGithubのリポジトリにPushすると自動でコンパイルを行いPDFを生成します.
ここではTeXファイルの名前をindex.texとしていますが,異なるファイル名の場合適宜設定ファイルを変更してください.
結果はGithubのActionsというタブを開くと見ることができ,それぞれのBuildを開くとの右上にArtifactsというメニューが有りそこからPDFをダウンロードすることができます.
Github Actionsの注意点としてはフリープランではPrivateリポジトリに対するGithub Actionsは2000分/月しか使うことができません.(一回のコンパイルは1~2分なのでそんなに影響ないですが...)複数のリポジトリを使っている場合は気をつけたほうが良いです.
Bitbucket
Bitbucket用の設定です.
BitbucketではPipelineという名前でGithubと同様の機能があります.これはbitbucket-pipelines.yml
という名前で設定ファイルを作成し,ディレクトリの直下に配置すると利用できます.
image: paperist/alpine-texlive-ja pipelines: default: - step: script: - latexmk index.tex artifacts: - index.pdf
これをcommitしてButbucketのリポジトリにPushすると自動でコンパイルを行いPDFを生成します.
ここではTeXファイルの名前をindex.texとしていますが,異なるファイル名の場合適宜設定ファイルを変更してください.
結果はBitbucketのPipelinesというタブを開くと見ることができ,それぞれのBuildを開くとの右上に雲のマークのボタンが有りそこからPDFをダウンロードすることができます.
Bitbucket pipelinesの注意点としてはフリープランでは50分/月しか使うことができません.Githubに比べて大分短いです.ちなみにStandard/Academicプランでは500分/月使うことができるのでこちらをおすすめします.
まとめ
論文はバージョン管理しましょう.
バージョン管理には適切なソフトを使用して決してファイル名で複数の版を管理するようなことをしてはいけません.
リポジトリはPrivateに!
GithubやBitbucket上でのCIの設定方法を示しました.
今後論文を書く方の参考になれば幸いです.
余談
弊研究室では行っていませんが,聞いた話によると論文のリポジトリに教授を招待し,IssueやPull Requestを通してレビューや修正を行っている研究室もあるようです.
レビューに関してはそれぞれやりやすい方法があると思うので一概には言えませんが,差分表示や行単位でのコメントに対応しているのでGithub等を用いてやり取りするのもいいですね.(作業量も可視化されてモチベーション上がるかもしれない)
また,ここでは紹介しませんでしたがtextlintと呼ばれる文書校正ツールが有りこれもCIに組み込むことができます.
ゼミ資料等を作成するときに使っていますが大変便利です.時間があればいつか書くかもしれません.