altnight/20240516.md

## 20240516.md

      
    Raw
  

              20240516.md
            
          
    2024/05/16 Git(GitHub)リポジトリの運用

自分の昨今の開発では、ほとんどGit(GitHub)を使っている。今回はそのあたりの情報やポリシーを整理してみた。Gitの話とGitHubの話は多少混ぜている。
触れていること

コミット(メッセージ/履歴)
ブランチ(命名/管理)
マージ
PR

触れていないこと

PRテンプレート
GitHub Actions
リポジトリとBTS(詳細)
Slack通知などの情報共有やチーム運営

開発的にはこういったリポジトリ管理より実際のコードや案件の問題に向き合うほうが重要性が高く、このへんはてきとうでいいという考え方もある。わからなくはないし、実際それで回っていることは多い。ただ、微妙なことはあった。
結果

前提


チーム開発(=1人ではない。もし1人で開発してても、将来引き継ぐ可能性が高い)
アプリ開発(=ライブラリ等ではない。特に、外部公開はしない)
デプロイ先は基本的に1つである(=複数バージョンを同時公開する可能性は低い。あったとしても先行試験などで+1つ程度)
スキルにある程度バラつきがある

最終的に2024/05時点での自分がどうしているか


ブランチ名: てきとう

ターミナルで補完が効けばいい
それなりに短い期間で削除される前提


コミットメッセージ: てきとう

wipとかfixでいい


マージ: Squash Merge

タイトルに概要を書き、詳細はPRの説明欄からコピペする
情報は可能な限りBTSではなくコード内、コミット履歴、リポジトリ内のドキュメントにまとめる


ブランチ運用: GitHub Flow

詳細

コミットメッセージ


いいコミットメッセージを書こうという習慣の話がある

whyをかく、prefixを合わせる、1コミットに1つの意味にする
結果としてPRのレビューが楽になる(という主張)
Semantic Commit Messages


これはこれでよい心掛けだけども、全部Squash Mergeするなら雑でもいい

コストをかけない


コミットが意味をもつ単位でやれるならアリ

バージョンアップ作業やリファクタリングで、一つずつやることを確実に積み重ねていくような場合


OSSで開発をしていて、外部に見せるという前提があるのなら、ありかもしれない

GitHubでのマージの3つの方法とどれを使うか


GitHubでサポートされているマージは3種類ある

Create a merge commit

--no-ff non-fast-forward
マージコミットが作成される


Squash and merge

--squash
コミットを圧縮して、新しいコミットを作成してマージする


Rebase and merge

(使ったことがない)


結論として、マージはほとんど Squash Merge でいいのでは?

履歴が整理される
PRの単位でまとまっていればよい


ほんとに --no-ff で履歴を残したい?

「XXX実装(実際にはいろいろ微妙に足りてない)」「wip」「レビュー反映」「修正」みたいなコミットを残したい?
git blame で履歴をたどりたい?
PRの単位でよくないか?
Squash Merge 時のコミットメッセージに情報を残す方が簡潔でよくないか?

GitHubのPRの変更内容をコピペするのがおすすめ(PRテンプレートを使用する想定)


大きめの機能実装ブランチをつくっていて、そこにはSquash Merge, mainにはMerge Commitならわかる

例: main <-(merge commit) feature-big-change <-(squash merge) change-1, change-2, change-3
ただその場合でも、基本的には「そもそもPRを細かくしてtopic branch を小さくしてそれぞれmainにマージすればいいので、そのブランチ運用自体をやめませんか?」とは思う


コミット履歴


バージョン管理システムとして履歴は可能な限り残し、使い手がフィルターするという考え方もある

可能な限りすべての情報を残すことで、その人/そのプロジェクトが考えていたことが残る
特に長く続くリポジトリにおいて、可能な限り多くのメタ情報が残る方がよいというポリシーもある


ただ、それらメリットは個人的にはあまり大きく感じない

多すぎる情報がノイズになる
チーム開発で習熟度にバラツキがある環境おいて、Gitの履歴を辿る操作を多くの人は使いこなせない


常にforce-push問題


なぜか常に開発者1人が触る topic branch の開発で、常に1commitに整理して force-push する行動をみかけることがある

ローカルで rebaseなり--amendなりでコミットを整理してからpushしているということだけども
PRでSquash Merge するなら、この作業は不要になる
コミットを見せたくないという意思の場合、基本的には小出ししにしてもらい、プロジェクトの方針で是正した方がよい
「コミットを1つにして履歴を残さないようにしている」ということ自体は致命的な問題にはならないとは思う。そういう意味では放置でもいいのだけど、技術的に変な行動を習慣にしてないか?という意味で、割れ窓的な危うさも感じる。


ブランチの削除


mainブランチはforce-pushを防ぐために保護しよう
ブランチは好きに作成し、好きに消せる
PRはブランチを削除しても残る
PRをマージした時に一緒にブランチを削除するとよい
PRをマージせずクローズしたり、hgリポジトリ移行でゴミとして残りがち
ブランチが残っていても直接問題にはならないが、デッドコードや閉じられてないチケットのように、情報が整理できていないという信号になってはいる

ブランチの命名


ブランチの名前はそもそもなんでもよい。てきとうでもいい
feature/xxx hotfix/xxx というprefixをつけるパターンがあるが

これは元々git-flowというブランチモデルがあったときの名残
GUIクライアントなどではディレクトリ風に表示してくれたりもするが、使わないことも多いので不要では


Redmineのチケット (例: t100111など)をつけるパターンがあるが

コミットメッセージに refs #100111 など


これは元々hg(Mercurial)かつRedmine連携があったときの名残
いまはGitHubを使用しているので、洗練された使いやすいWebUIがある

コミットも個別にWebUIで見れるし、PRやIssueに簡単に紐付けられる


なので、いまはこの命名規則を使う理由が減っている
ターミナルでの補完のことを考えると、てきとうに開発中の内容を書くの方がわかりやすい
<sprint-number>-<some_feature> という命名もまあまあ悪くなかった
とはいえ最終的にはブランチは削除するのが基本とすると、やはりてきとうでもよい

PRのタイトル


GitHubでは BPR-100111 みたいにPrefixを設定することで、外部のBTSなどにリンクを作成できる
#100111 などは、GitHubのリンクになる
そのため、 #100111 はGitHubのリソースを示し、Redmine/Jira/BacklogなどはPrefixを使用すべき

過去の名残や習慣かなにかで、外のBTSのリンクを #10011 のように記載していることがある。これはただの形骸化なので、やめるべき

これが対応できないのは、技術というよりは、チームの運用の問題にみえる


Git-FlowとGitHub-Flow


Git-Flow: (main - develop - topic) + hotfix
GitHub-Flow: main - topic
かつては Git-Flow でちゃんとやろう的な風潮もあったが、アプリ開発としてはGitHub-Flow で十分
ブランチが多段になって扱いが難しくなりコンフリクトが発生する可能性が上がる

GitFlowをまともに運用するなら、コミットが独立していないと意味がない
OSSのライブラリのプロダクト等で複数(パッチ)バージョンが存在するならよいかもしれないが


hotfixはmainから生やした使い捨てブランチでよいのでは
リリースはmainから生やしたtagでよいのでは

直接mainブランチ指定でもよい


お客様の運用的にGitFlowから変えられないこともあるが、可能な限りはGitHub-Flowを推奨してなるべく変えてもらう

Git-Flowにした場合でも、mainブランチへのマージがただの儀式になってる
同じ儀式ならtag発行の方がまだ気が楽


リポジトリの情報密度を上げるかどうか


開発で触るコード(リポジトリ)に対して、BTSの情報は遠いという感覚がある

1クリックかかるというのもあるし、BTSのチケットやwikiの情報は実情として雑多なメモだったりして、整理されてないこともある

整理されていない生の情報でも流しつつ作業する、という意味ではBTSの意義はあるのだけど


コード(リポジトリ)は残るが、BTSは消えることがある

なので、なるべくBTSよりリポジトリに集約したいという気持ちはあったが
まあBTSが参照できなくなるような状況になっている時点で、会社ごと変わってリプレイスしたりとかなので、そういう意味ではなにをどうしようが手遅れではある


1つのプロジェクトに対して複数のリポジトリを持つ場合、情報をBTSに集約したいという話

それはわかる
そもそもリポジトリを分割しすぎない方がよいとは思うが(モノレポ)