review.md

git, github を使った文書の相互レビュー

論文や学会の概要など、文書を複数人でブラッシュアップするとき、 git, githubを使うと便利である。

ここでは、そのやりとりについての簡単なルールをまとめる。

ワークフローの例

コンセプト

• 一つの文書・著者一人あたりに、一つのブランチを作って、その中でファイルを更新していく。
• 初稿の段階で master にそのブランチの Pull Request を送る。
• 複数回の修正が繰り返される場合は、上記 Pull Request 内でやり取りを行なう。
• 最終的に文書が完成してサブミットする段階になると、そのブランチを master ブランチにマージする。

準備

おおよそ年度ごと、研究室の文書を格納する(プライベート)リポジトリを用意しておく。
文書ごとにディレクトリを作成しておく。 ディレクトリ構造は以下のようにする。

─ documents_20**.git
　　└ 学会名 or 論文名
　　　　└ 著者名
　　　　　　├ TeX ファイル1
　　　　　　├ TeX ファイル2
　　　　　　│　　…
　　　　　　└ サブディレクトリ
　　　　　　　　　├ ファイル1
　　　　　　　　　├ ファイル2
　　　　　　　　　│　　…
　　　　　　　　　　

著者 (初稿)

1. 文書を作成する前に、masterブランチから新たなブランチを作成しそれをチェックアウトする。
2. 文書を作成し、完成すればコミットする。
3. レビュアーに送る準備ができれば、master ブランチに対して Pull Requestを送る。

レビュアー (修正作業)

1. Pull Request を受け取れば、そのブランチをローカルに Pull する。
2. そのブランチ内でファイルを修正する。
   その際、コメントはGit hub内で書くよりも、ファイルのコメント欄に書くほうが良さそう。 3. コメントの入力が終了すれば、修正したファイルをcommit, pushする。 Github の Pullrequest 内にコメントを書いたほうが、議論の過程がわかりやすそう。
3. 上記 Pull Request 内にコメントを記入することで、著者に通知が届く。

著者 (第二稿 以降)

1. Pull Requestにコメントが記入され、レビュアーによりファイルが更新されていれば、
   Pull することでリモートでのファイルの更新をローカルに反映させる。
2. レビュアーのコメントに従ってファイルを更新する。
3. 文書が完成すれば、同じブランチに commit, pushする。
4. 上記 Pull Request 内にコメントを記入することで、レビュアーに通知が届く。

完成

著者とレビュアーとのやりとりを繰り返して、文書が完成すれば、 上記の Pull Request を master ブランチにマージする。

その他

• TeX の環境構築についてはこちらを参照のこと
• 各ファイルの差分については git 標準のツールで確認できるが、pdfベースで差分を確認したい場合は こちらを参考にする。
  なお、特定のコミットと現在のファイルとの差分をpdfベースで見たい場合は、
  ./git-latexdiff {sha id}
  を実行することで確認できる。ここで、sha id はコミットに紐付けられたidである。