こんにちは、M1 のらんです。今回は、GitHub の Pull Request 機能を使った論文添削の魅力について紹介します。

GitHub の Pull Request 機能は、コードの変更を提案し、それをレビューしてマージするための仕組みです。システム開発では、機能追加やバグ修正などの変更を、Pull Request として提案し、レビューを受けてマージすることが一般的です。この Pull Request 機能は、論文添削においても非常に有用だと考えています。実際に、本研究室では本年度から卒論添削で利用しています。そこで本記事では、Pull Request 機能を使った論文添削のメリットや運用方法について紹介します。

また、卒業論文のための GitHub 運用法 についても、併せてご覧ください。

前提

Git における branch の概念を理解していることを前提として解説します。

なにが嬉しいか

GitHub の Pull Request 機能では、レビューコメントを投稿できます。論文添削では、以下のような恩恵があると考えています。

• Suggestion 機能で、レビューコメント内で修正案を提案できる
• 他のレビュアーのコメントを閲覧できる
• 解決済みマークで、修正済みかを判別できる

Pull Request でのコメント手順については、プルリクエストへのコメント – GitHub Docsを参照してください。

Suggestion 機能

これめちゃくちゃおすすめの機能なんですが、Pull Request で修正案を提案するときに便利な機能です。レビュワーは、コメントフィールドで をクリックすると、選択箇所の修正案を提案できます。（参考：プルリクエストに行コメントを追加 – GitHub Docs）

また、執筆者は、レビュワーの提案に対して「Commit suggestion」をクリックすることで、GitHub 上で修正 commit をすることができます。（参考：提案された変更の適用 – GitHub Docs）紙や PDF ファイルでの論文添削では、修正案を適用する際にいちいち手作業で修正する必要があります。一方 Suggestion 機能ではワンクリックで修正案を適用できるので、非常に便利です。時短になり、より本質的な議論に集中できます。

他のレビュアーのコメントを閲覧できる

レビュワー間でコメントを閲覧できることもメリットだと思います。複数人のレビュワーがいる場合の論文添削では、重複したコメントが出ることがあり得ます。紙や PDF での論文添削では、他のレビュワーが既に指摘していると知らずに同じ指摘をしてしまうことが多々あります。このような二度手間を防ぐためにも、レビュワー間でコメントを閲覧できることは有用です。

他にも、他のレビュワーの添削が見れることで、執筆者-レビュワー間だけでなく、レビュワー-レビュワー間でも、知見を共有できます。このような教育効果も期待できると考えています。

解決済みマーク

執筆者は、投稿されたコメントに対して、解決済みマークをつけることができます。（参考：会話を解決する – GitHub Docs）

論文添削でよくあるのが、執筆者が、どのコメントの修正を行ったか/行っていないかを把握することが難しい時があります。紙での論文添削では、私は、修正箇所に印をつけることで修正済みかを判別していましたが、コメント量が多くなるほど手間がかかるなと感じていました。

一方で、解決済みマークがつけられたコメントは、会話全体が畳まれ、まだ対応が必要な会話を見つけやすくなります。

Pull Request の作成方針

論文添削を Pull Request 機能を用いて行う良い運用方法を考えてみましょう。まず基本方針として、執筆用ブランチとレビュー用ブランチを用意し、これらのブランチ間で Pull Request を作成します。このレビュー用ブランチの作成方法がポイントとなります。Pull Request でレビュー対象にできる変更は、2 ブランチ間の差分となります。論文添削では、特定の commit の diff だけ〜とかではなく、執筆したすべての diff をレビュー対象としたいですよね。

では、すべての執筆対象を Pull Request の diff とするにはどうすればよいでしょうか。良い案を考えました。

init commit からレビュー用ブランチを作成します。そして、執筆用ブランチ → レビュー用ブランチへの Pull Request を作成します。こうすることで、執筆用ブランチのすべての変更がレビュー対象となります。このような方針で Pull Request を作成します。この後の作業の注意点としては、Pull Request は mergeしないでください。誤 merge しないように、Draft としてCreate Pull Request できれば一番いいんですが、プライベートリポジトリだと有料プランが必要です。

この運用の嬉しいところは、執筆用ブランチを一切触らなくてもよい手軽さです。もし、執筆用ブランチに新しいcommitがあっても、新たに必要な作業はありません。

使用手順

上記の方針を踏まえて、実際に Pull Request を作成する具体的な手順を解説します。

※ GitHub CLI をインストールしておいてください。

1. レビュー用Pull Reqestの作成

ローカルリポジトリにて以下のシェルワンライナーをペーストすると、レビュー用のブランチがpushされ、Pull Requestの作成までしてくれます。

git branch review $(git rev-list --max-parents=0 HEAD | tail -n 1) \
&& git push origin review \
&& gh pr create --base review --head main --title "レビュー用" --body "レビュー用PRです。マージはしないでください。"

2. 作成した Pull Request ページにてレビュー作業

プルリクエストへのコメント – GitHub Docsを参照してください。

おわりに

Pull Request 機能を使った論文添削のメリットや運用方法について紹介しました。本研究室でも実践していて、非常に有用だと感じたので今回共有しました。論文執筆では、レビュー&修正を繰り返し、ブラッシュアップし続けることが重要です。効率的に執筆を進めるために、Pull Request 機能を使ってみてはいかがでしょうか。