研究でのGit運用方法

どうもこんにちは,Megです.

Meg

機械学習と脳疾患を専門に勉強している、理系男子大学院生です。

大学の学部では生命工学を学び、男子の中で成績1位を取るほどの勉強好き。

主に生機械学習と生活改善を中心に、日々の学びで得た知識やヒントをブログで共有していきます!

Megをフォローする

今回は,研究でGitとGitHubを上手く使い,研究生活を効率化させるための記事です.

普段の研究でのGitの使い方だから参考にしてみて!

はじめに

前提条件として,

  • 個人のローカルマシンにおいて,Gitの環境構築
  • GitHubで個人アカウント作成が完了
  • AcademiXリモートリポジトリの編集権限の付与

上記2点が済んでいることとします.

また,複数人での開発ではなく,基本的に一人でコードを書いていく方向けです.

少し改変すれば複数人の開発でも使えるよ

フォルダ構造

リポジトリの構成は,Cookiecutter Data Scienceのものを使用しています.

Home - Cookiecutter Data Science
A project template and directory structure for Python data science projects.

上記ページに詳細・インストール方が記載されています.以下,自分のテンプレートのオプション選択を記載します.

Select open_source_license:
1 - MIT
2 - BSD-3-Clause
3 - No license file
Choose from 1, 2, 3 (1, 2, 3) [1]: 1
Select python_interpreter:
1 - python3
2 - python
Choose from 1, 2 (1, 2) [1]: 1

ライセンスはMITライセンス,pythonはpython3を使用しています.

研究でのライセンスはどれが良いのかはわかっていない…

ブランチ運用

GitHubにおけるブランチ運用法は,以下のサイトに多く記載されています.

Gitにおけるブランチ戦略について調べてみた - Qiita
なんとなく使っているGitブランチ、みんなどうやって管理しているのだろう? その謎を解明すべく、我々はジャングルの奥地へと向かった。 1.ブランチとは Git上で別々の作業を並行して行うための仕組みをブランチという。 # te...

研究活動が前提なので,開発メンバーが基本的に自分一人であることと,運用方法の学習コストを下げるために,GitHub flowを採用しています.

GitHub flow

GitHub社で利用されている開発フローです.
mainブランチとfeatureブランチの2つのみで構成されていることが特徴です.

詳細は以下のサイトを参照してください.

GitHub フロー - GitHub Docs
GitHub フローに従って、プロジェクトで共同作業を行います。

以下,GitHub flowによる開発の流れを示します.

  1. issueを作成
  2. issueからブランチを作成
  3. ブランチ上で作業
  4. コミットメッセージを作成
  5. pull requestを作成
  6. レビューコメントに対応
  7. pull requestをマージ
  8. ブランチを削除
  9. issueを封鎖

issueを作成

作業のスタートとして,GitHub上でissueを作成するところから始めます.

このようなissue中心で開発を進めていくことを,issueドリブン開発と呼びます.

GitHubページ右上のNew issueからissueを作成します.

issueタイトル

issueタイトルは英数字で30字以内で記述します.
「30字以内」はあくまで目安であり,簡潔に作業内容を要約することを心がけましょう.

issueは1トピックで作成

これは,指導教官や先輩からレビューを受ける際に,1トピックの方がレビューする内容が少なく,作業者とレビュアー共の心理的負担を下げることができます.
ゆえに,こまめなレビューを行ってもらうことができ,研究に関与する全員が研究の全容を把握できます.

研究は進んでいない時こそすぐ共有.これはMegとの約束なっ

issueタイトルの例

issue内容

Leave a commentの欄に,作業内容を記載します.
チェックボックスなどを活用し,ToDoレベルに作業内容を記載することがコツです.

issue内容の例

内容を記載し終えたら,右下のsubmit new issueを押してissueを発行します.

issueからブランチを作成

issue作成後,下図の右下にあるDevelopmentのCreate a branchから新しいbranchを作成します.

右下の青字です

ブランチ命名規則

Create a branchを押すと,ブランチの作成画面に移ります.

ここでbranch nameは,issue IDとタイトルのスペースにハイフンを入れたものになっています.

ブランチを作成

タイトルを変更後,Create branchを押してブランチを作成する.

すると,以下の画面に遷移する.

下記コマンドをコピーし,エディタやターミナルにペーストすることで,ブランチを切り替える.

git fetch origin
git checkout 2-make-git-rule

作成したブランチ上で作業

ブランチが作成できたので,実際に作業を進めていきます.開発環境は,それぞれの研究室に従ってください!

ただ,Google Colaboratoryを開発環境として使用する例を挙げておきます.

Google Colaboratoryにアクセスすると,GitHub上のファイルを操作できます.作成したブランチを選択後,ファイルを新規作成・編集し作業をしていきます.

コミットメッセージを作成

以下に推奨するコミットタイミングを示します.

  • issueのチェックボックスを完了したタイミング
  • その日の業務を終了するタイミング
  • 下記に示す,Prefixに当たる作業を完了したタイミング

コミット関連のコマンド操作は,ローカルリポジトリが登録されているマシン上で行います.

コミットメッセージ形式

コミットメッセージは3行に渡って記述しましょう.

1行目:タイトル
2行目:空行
3行目:本文

コミットタイトル

以下にコミットタイトルの命名規則を示します.

Prefixを記載

Prefixとは,テキストの先頭につける単語のことです.
Angular.js/DEVELOPERS.mdのPrefixを採用しています.

feat: A new feature

fix: A bug fix

docs: Documentation only changes

style: Changes that do not affect the meaning of the code (white-space,formatting, missing semi-colons, etc)

refactor: A code change that neither fixes a bug nor adds a feature

perf: A code change that improves performance

test: Adding missing or correcting existing tests

chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

日本語で目的語+動名詞の形で記述

研究室のメンバーは日本語を母語としている方のみなので,コミットメッセージのタイトル(本文)は日本語で記載します.
タイトルの形式を揃えるために,目的語+動名詞の形式でタイトルを記述しましょう.
これは,主語が不必要であり,文体の時制も揃うというメリットがあります.

Ex)

○ ブランチとコミットの命名規則に関する資料を作成

☓ 私はブランチとコミットの命名規則に関する資料を作成した

コミットタイトルは30字以内で記述

「30字以内」はあくまで目安であり,簡潔に作業内容を要約することを心がけましょう.
句点が入る分量は長いので,内容を要約できないか見直すことをオススメします.

Ex)

○ ブランチとコミットの命名規則に関する資料を作成

☓ 大学における学生の研究活動を主な対象とした,GitHubにおけるブランチとコミットの命名規則に関する資料を,Markdown形式で作成

コミット本文

作業した内容を日本語で記述します.レビューする相手のことを考え,主語・述語を適切に書きましょう.
「何をなぜ作業したのか」に重点を置いて書くことがポイントです.

コミットタイトルと本文は,日本語が非母語の方がいたら英語で書くと良いかも

Ex)

大学における学生の研究活動を主な対象とした,Gitのブランチ・コミット名の命名規則に関する資料を作成.
GitHub flowによるブランチ運営方法を採用.

コミットメッセージを記述するエディタ

コミットメッセージを記載する際,

git commit

コマンドを使用します.
デフォルトだとターミナルでコミットメッセージを記述することになりますが,使用感が良くないので手元のエディタでコミットメッセージを編集できるようにすることをオススメします.

以下,コミットメッセージをVS Codeに変更するコマンドを以下に示します.

$ git config --global core.editor 'code --wait'

詳細は以下の記事を参照してください.

GitのエディターをVScodeに設定する方法(Macユーザー向け) - Qiita
はじめに コミットメッセージの入力などでVScodeを使えるように設定していく手順を解説していきます。 前提として、Gitはローカル環境にインストールした状態にしておいてください。 GitのエディターにVScodeを設定する...

pull requestを作成

以下のコマンドにより,作業を加えたブランチをリモートリポジトリに送ることで,pull requestを作成できます.

git push origin 送るブランチ名

基本,1ブランチにつき変更を加える開発者は1名になるので,コードの保存も兼ねてこまめにpushしましょう.

pull requestを送るタイミングは,issueの問題が自己解決した時を基本としていますが,開発途中でも他の研究室メンバーと議論したい時にも作成することは効果的です.

レビューコメントを記述&対応

後輩指導などで,自分にpull requestが送られてきたら,そのブランチをローカルリポジトリに取り込み,コードレビューをしましょう.

git pull origin 取り込むブランチ名

レビューをして,変更を加えた方が良い箇所には,pull requestに記載しましょう.
特に問題がなければ,「レビューしました」等とpull requestに返信し,レビューをした旨を伝えましょう.

ここで労いの言葉の一つでもかけたら研究室内の株は急上昇だね!

リモートリポジトリとローカルリポジトリのmainブランチを同期

タイミングは個々人の裁量によりますが,リモートリポジトリとローカルリポジトリのmainブランチをこまめに同期することをオススメします.

なるべくリモートとローカルリポジトリは同期させときたい

ローカルリポジトリのmainブランチに移り,以下のコマンドを実行すると,リモートリポジトリとローカルリポジトリを同期することができます.

git pull origin main

pull requestをマージ

自分以外のメンバーからレビューを受けて,問題が無かったら,ブランチをmainブランチにマージしていきます.
GitHub上のpull requestページから,pull requestを作成した本人がMerge pull requestを押して,mainブランチに内容をマージします.

ブランチを削除

マージした後,Delete branchを押して自分が作成したブランチを削除しましょう.

issueを封鎖

pull requestをマージした後,GitHubからClose issueを押してissueを封鎖します.

最後に

以上で研究室でのGit運用法の説明を終わります.素敵なGit生活を!

Gitに慣れると全てをバージョン管理したくなるよ

参考文献

  1. Rick Umali.独習Git.吉川邦夫訳.株式会社翔泳社,2020.
  2. 大塚弘記.WEB+DB PRESS plusシリーズ:GitHub実践入門 -Pull Requestによる開発の変革.株式会社技術評論社,2019.
タイトルとURLをコピーしました