卒業論文のためのGitHub運用法

2024-01-08 最終更新日時 : 2024-01-08 Ran350

M1のらんです。さて、今年も卒論修論の季節がやってきました。サイバーセキュリティ研究室では、昨年12月初旬に卒業論文を控えたB4向けに 卒論執筆講座を開催し、以下について共有しました。

  1. 卒論のためのGitHub運用法（本記事で紹介）
  2. 卒論執筆 指南書（卒論に迷えるB4生へ 卒論執筆 指南書を授けたい にて紹介）

本記事では、卒論執筆講座の内容を抜粋して「1. 卒論のためのGitHub運用法」ついて紹介します。

⚠️ なお、本卒論執筆講座はサイバーセキュリティ研究室のB4向けに作成したものであり、 研究室の文化によってベストプラクティスは異なることには留意してご覧ください。

⚠️ サイバーセキュリティ研究室の文化を鑑みて、本講座での推奨手順はあくまで推奨であり、強制とはしていません。

GitHubリポジトリを採用する恩恵

まずはじめに，絶対に卒研のデータのバックアップを取っておきましょう． なぜか卒論時期に限ってマシンの故障が頻発します． 提出間近になって PC が壊れてしまい，提出できなくなるという悲惨な事故は起こり得ます． そうならないように，ローカル環境だけでなく OneDrive や Google Drive，GitHub などのクラウドサービスにバックアップ体制を構築しておきましょう．

これらのバックアップ環境の中でも，本研究室では以下の環境を推奨します．

研究室の GitHub Organization に紐づいたプライベートリポジトリ

理由としては，

  • バージョン管理をしたい: Git を使用することで，データの変更履歴を管理し，誤った更新やデータ損失が発生した場合に簡単に元の状態に戻せる．
  • レビュワーがアクセスしやすい: 論文執筆の進捗共有やレビュー作業のために，執筆途中の論文データを研究室内で共有したい．ここで，もし個人アカウントでリポジトリを作成してしまった場合，レビュワーをリポジトリへ招待しないといけない．これは面倒．Organization のリポジトリにしておけばそのような手間はなくなる．
  • レビュー機能を使える: GitHub の Issue や Pull Request，Permalink 機能を用いたレビューができる．

Git の使い方を知る

講座では、卒論執筆にあたり最低限覚えたいGitの操作方法を紹介しました。

  • Git とは何か
  • git init: ワークスペースを作成する操作
  • git add: 記録する変更を選ぶ操作
  • git commit: 変更を記録する操作
  • git push: 記録した変更をリモートリポジトリに共有する操作

Git入門資料

困った時は，ChatGPT に「Git で〜したい時はどうすれば良い？」って聞いてみるのもいいかも．

卒論執筆における Git の心得
  • こまめに push すべし：少なくとも一日の作業終わりには必ず git push．いやいや、一息ついたら git push
  • PDF も Git 管理すべし：LaTeX コンパイルが通らなくなるなど，前バージョンの PDF を参照したいときは多い．あと，レビュー時に GitHub から閲覧できるも便利．
  • commit 戦略こだわるべからず：実開発であれば commit するタイミングや commit message をこだわるところだが，卒論執筆ではその必要はない．一息ついたタイミングで commit/push しよう．それより論文の完成度を高めることを優先しよう．ちなみに，GitHub Copilot に commit message を生成してもらうこともできるので気になる人はぜひ．

Git/GitHub環境を用意する

卒論執筆講座では、各々のGitHubリポジトリを作成してもらい、ワークショップも兼ねて init commit を pushしてもらいました。

  1. GitHub アカウントの作成，サイバーセキュリティ研究室の Organization への追加
  2. git コマンドのインストール
  3. gh コマンドのインストール：GitHub CLI めっちゃ楽なのでおすすめ．SSH キーの登録も必要ない．
  4. リポジトリの作成，研究室Organization の private リポジトリとして
  5. 本研究室で作成している卒論TeXテンプレートを手元に用意
  6. ローカル環境で、執筆用ディレクトリを任意の名前に変更
  7. git init
  8. git add / git commit
  9. init commit を push
  10. GitHub に反映されたか確認してみよう

手元の LaTeX 環境が動かない😭となったら

執筆中よくある場面として、コンパイルエラーが出るが自分が書いたTeXコードが悪いのか、手元のLaTeX環境が悪いのか判別したいということがあります。そんな時には、

 CyTeX を試してみて！

もし、CyTeX環境でもコンパイルエラーが出るならTeXコードが悪そう、CyTeX環境でエラーが出ないならローカル環境が悪そう、のように一つの判断基準として使えます。

CyTeX は、私が開発している、GitHub Codespaces を用いたLaTeX 環境テンプレートです。 ローカル環境に texlive や Docker をインストールせずに、GitHub Codespace 上のクラウド開発環境に LaTeX 環境を構築できます。 または、devContainer を用いて、Codespace 環境ではなくローカル環境に構築することも可能です。

使用方法は簡単で、執筆中のGitHubリポジトリに、設定ファイルを置くだけです。 詳しくは、CyTeXリポジトリのREADME をご参照ください。技術構成や開発経緯については、GitHub Codespacesを用いた日本語LaTeX執筆環境『CyTeX』を作った話 で紹介しています。

GitHub でレビューをしてもらう

Git/GitHub での作業に慣れてる人向けにはなりますが，GitHub の Issue や Pull Request 機能を用いたレビュー方法もあるので紹介しておきます．

Pull Request でのレビューの場合，ファイル diff が見やすくなったり，suggestion コメント機能が使えたりと便利な機能が使えます． ただ、Git初学者にとっては Pull Request を作成するまでの工程が難しいかもしれません．

他方で，GitHub Issue でのレビューの場合は特に Git の操作を行う必要なく簡単に始められます． diff や suggestion コメント機能はありませんが，Permalink でコードを参照しながらレビューコメントすることができます．

GitHub Issue でレビューを受けたい場合

GItHub Issue や Permalink について知りたい場合は以下をご確認ください．

GitHub Issue でレビューを受けたい場合，以下のようなフローが考えられます．

  1. レビュイーが，レビュー用の Issue を作成する．（github.com/cysec-lab/{repo}/issues/new）
  2. レビュワーが，レビューで参照したい箇所の Permalink を作成する．
  3. レビュワーが，Issue に Permalink とレビューコメントを記載し，コメントを投稿する．
  4. レビュイーが，コメントを確認して修正．（Tips：Issue コメントへのスタンプを，修正ステータスにするのもよさそう）

Pull Request でのレビューを受けたい場合

GItHub PullRequest について知りたい場合は以下をご確認ください．

Pull Request でのレビューを受けたい場合，以下のようなフローが考えられます．

  1. レビュー用のブランチを作成するため，init commit から branch を生やして push する．
  2. GitHub の Pull Request 作成ページにアクセスする．
  3. レビュー用 branch を base branch，執筆作業をしている branch を head branch として Pull Request を作成する．

base/head branch について知りたい場合は以下をご参照ください．

おわりに

授業外でそこまで開発しない学部生にとって、Git操作に慣れている人は多くないというのが現状です。ただ、情報系学部を修了する人として Git には慣れ親しんでいて欲しい、という思いで今回開講しました。本講座後、卒論TeXファイルだけでなく、研究用のプログラムもGit管理する人が増えて嬉しく感じています ☺️

カテゴリー
論文
タグ

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

前の記事
卒論に迷えるB4生へ 卒論執筆 指南書を授けたい
2024-01-07
次の記事
GitHub Pull Request をもちいた論文レビュー添削のすゝめ
2024-01-14