roadmap.sh のどこをやっているか
- GitHub / GitLab / Bitbucket とプルリクエスト
- コードレビューとドキュメントの置き場
この記事は、上の項目を実際に手を動かして確かめる回です。
前回: 同じボタンが3種類できる理由 — デザインシステム 作業場所はVMの中(Ubuntu Server)です。GitHubに上げた
~/serverと、前に作ったCIがそのまま動いている状態から始めます。ブランチ保護の設定だけ、Windows側のブラウザを使います。
ここまで、コードはずっと main に直接コミットしてきました。
書いて、git add して、git commit して、git push。速いし、迷うところがありません。一人なので、誰の邪魔にもなりません。
問題は、速さではなく「戻せなくなる瞬間」です。
たとえば、こういう2時間です。認証まわりを直しはじめて、途中でログの出し方が気に入らなくなって直して、ついでにインデントを揃えて、その途中でバグを見つけて直して、main に3回 push しました。そして、動かなくなりました。
このとき、あなたが知りたいのは「どの変更が壊したのか」です。ところが main の履歴には、認証・ログ・整形・バグ修正が混ざった3つのコミットしか残っていません。1つ戻すと、関係ない修正まで消えます。全部戻すと、2時間が消えます。
そして、いま動いているサービスは main から動いています。 壊れたものが、そのまま本番の位置にあります。
これは人数の問題ではありません。「作業中のものと、動いてよいものが同じ場所にある」という置き方の問題です。だから一人でも直せます。
この回でやるのは、精神論ではありません。ブランチを切って、PRを作って、自分でレビューして、マージする、という一周を実際に回します。そして、CIが落ちたPRは自分でもマージできないように、機械の側に鍵をかけます。
対象レベル: 中級 / 区分: 必修
この記事でわかること
mainに直接コミットする問題は「速さ」ではなく「作業中のものが本番の位置にある」こと- PRは他人に見せるための機能ではないこと。一人なら、未来の自分に向けたチェックリストになる
- 自分のプルリクエストは、自分でApproveできないこと。だから一人のときは「レビュー必須」を設定してはいけない
- レビューで見るのは「好み」ではないこと。見るべきものは5つに絞れる
- ブランチ戦略は GitHub Flow で十分で、Git Flow は一人には重すぎること
この記事でやること
- ブランチを切って変更し、push して、プルリクエストを作る(
ghかブラウザ) - 自分のPRを自分でレビューする。見るところをチェックリストにして、実際に指摘を書く
- ブランチ保護を入れて、CIが落ちたPRはマージできない状態にする
- わざとCIを落として、マージボタンが押せなくなることを確かめる
- コンフリクトをわざと起こして、直す。そして中止の仕方も覚える
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| ブランチ | 履歴の枝。main から分かれて作業し、あとで合流させる |
| プルリクエスト(PR) | 「この枝を main に合流させたい」という申請。GitHub の機能で、Git そのものの機能ではない |
| マージ | 枝を合流させること |
| コンフリクト | 合流させようとしたとき、同じ行が両側で違う内容に変わっていて機械が決められない状態 |
| ブランチ保護 / ルールセット | 「この条件を満たすまで main に入れさせない」という GitHub 側の鍵 |
| ステータスチェック | PRに対して走る自動チェック。前回作ったCIがこれになる |
| レビュー | 変更を読んで、マージしてよいかを判断すること。Approve / Comment / Request changes の3種類がある |
gh | GitHub 公式のコマンドラインツール。ブラウザを開かずにPRを作れる |
① main に直接コミットすると、何が戻せなくなるのか
まず、いまの状態を見てください。
* main
枝が1本しかありません。 * が「いまここにいる」という印です。
この状態の何が困るのかを、言葉ではなく履歴で見ます。
コミットが並びます。ここで、そのうち1つだけを取り消したいと考えてみてください。
revert は「そのコミットと逆の変更を、新しいコミットとして足す」コマンドです。履歴を消さずに打ち消すので、push 済みでも安全です。
問題は、コミットの中身が混ざっているときです。 1つのコミットに「認証の修正」と「インデント揃え」が両方入っていると、revert は両方を打ち消します。片方だけ残すことはできません。混ぜた時点で、分けて戻す手段が消えています。
もうひとつ、もっと直接的な困りごとがあります。
途中まで書いたコードが ~/server にある状態で、別の急ぎの修正が必要になったとします。 いまのやり方だと、選べる道は「書きかけを捨てる」か「書きかけごと push する」しかありません。
ブランチは、この2つを同時に解きます。
main に直接 | ブランチを使う | |
|---|---|---|
| 作業中のコードの置き場所 | main(=本番と同じ枝) | 別の枝 |
| 1つだけ戻したい | 混ざっていると無理 | 枝ごと捨てれば消える |
| 途中で別件が来た | 捨てるか、混ぜるか | 枝を切り替えるだけ |
壊れたコードが main に入る | 止める人がいない | CIとブランチ保護が止める |
「一人だから要らない」ではありません。「一人だから、止めてくれる人が誰もいない」のです。
② ブランチを切る
まず、main を最新にします。
そのうえで、枝を作ります。
Switched to a new branch 'feat/health-endpoint'
switch -c の -c は create です。「作って、そこに移る」を一度にやります。
git checkout -bと同じです。checkoutは「ブランチ切り替え」と「ファイルを元に戻す」という別の仕事を1つのコマンドが持っていたので、Git 2.23 でswitch(枝の切り替え)とrestore(ファイルを戻す)に分けられました。古い記事はcheckoutで書かれていますが、どちらも動きます。
確かめます。
* feat/health-endpoint
main
枝の名前の付け方に決まりはありませんが、あとで一覧を見たときに何の枝か分かるようにします。この記事では次の形を使います。
| 接頭辞 | 何の枝か |
|---|---|
feat/ | 機能を足す |
fix/ | 不具合を直す |
docs/ | ドキュメントだけ |
chore/ | 設定・整理など、動作が変わらないもの |
③ 変更して、push する
枝の中で、小さな変更を1つだけします。 例として「サーバーが生きているかを返すエンドポイント」を足します。
~/server の中身は人によって違うので、ここは自分のコードに合わせてください。 Express なら、ルーティングを書いている場所に1つ足すだけです。
app.get('/health', (req, res) => {
res.json({ status: 'ok' });
});
変更を確かめます。
足した行だけが出てくれば正解です。 ここで関係ない行が大量に出てきたら、整形が混ざっています。(対処は⑧に書きます)
コミットして、枝ごと push します。
-u(--set-upstream)は「この枝の push 先はここ」と覚えさせる指定です。次からは git push だけで済みます。
remote: Create a pull request for 'feat/health-endpoint' on GitHub by visiting:
remote: https://github.com/<ユーザー名>/server/pull/new/feat/health-endpoint
GitHub が「PRを作れますよ」とURLを返してきます。 これが次の手順です。
ここで
mainは1文字も変わっていません。 ブラウザでmainを見ると、/healthはまだありません。作業中のものが、本番の位置に無い状態が作れました。
④ プルリクエストを作る
2つの道があります。どちらでも同じものができます。
道A: ブラウザで作る
上のURLをWindows側のブラウザで開くと、PR作成画面が出ます。タイトルと説明を書いて「Create pull request」を押すだけです。
[スクリーンショット: 01_pr作成画面.png] GitHub のプルリクエスト作成画面を撮ってください。タイトル欄と説明欄、下に差分が出ている状態です。
道B: VMの中から gh で作る
ブラウザに切り替えずに済むので、慣れるとこちらが速いです。
まず入っているか確認します。
command not found なら入れます。Ubuntu の標準リポジトリにも gh がありますが、版が古いことがあります。 まずこちらを見てください。
候補が出てくるなら、それで十分です。
出てこない(Unable to locate package)場合は、GitHub 公式の手順に従います。 最新の手順は公式の案内にあります。外部のリポジトリを足す操作なので、コピペで済ませず、リンク先の手順をそのまま使ってください。
入ったら、ログインします。
対話で聞かれます。GitHub.com → SSH → 既存の鍵を使う、を選んでください。 前にGitHubに登録した鍵がそのまま使えます。ブラウザでのワンタイムコード入力を求められるので、画面の指示どおりに進めます。
確認します。
PRを作ります。
https://github.com/<ユーザー名>/server/pull/1
URLが返ってきたら成功です。
中身をVMの中から見られます。
--bodyを空にしないでください。 一人でも、3週間後の自分は他人です。「なぜこれを足したのか」は、コードの差分には書いてありません。
⑤ 自分でレビューする — 見るところを5つに絞る
ここが、この記事で一番大事なところです。
PRの Files changed タブを開きます。そして、自分が書いたコードを、他人が書いたものとして読みます。
[スクリーンショット: 02_差分レビュー.png] PRの Files changed タブで、行にコメントを付けている画面を撮ってください。
「よく見る」では何も見えません。見る順番を決めます。
レビューのチェックリスト
| # | 見ること | 具体的に何を確かめるか |
|---|---|---|
| 1 | 動くか | CIは緑か。手元でも動かしたか。エラーのときの分岐も通したか |
| 2 | 読めるか | 名前で意味が分かるか。説明のコメントが要る箇所は、コードのほうを直せないか |
| 3 | 戻せるか | これだけを revert して元に戻るか。DBの構造変更やデータ移行が混ざっていないか |
| 4 | 秘密が入っていないか | APIキー・パスワード・トークン・自分のIPやドメイン。.env が差分に出ていないか |
| 5 | テストがあるか | この変更が壊れたとき、CIが気づくか。気づかないなら、テストが無い |
上から順に見ます。1が×なら、2以降は読む価値がありません。
実際に、いまのPRで4番を機械的に確かめます。
src/app.js | 4 ++++
1 file changed, 4 insertions(+)
変更したファイルが1つだけです。 ここに .env や id_rsa が出てきたら、その時点で止めます。(秘密の扱いは別の回でやりました)
中身の文字列も見ます。
何も出ないのが正解です。 出たら、それが変数名なのか、値そのものなのかを必ず目で確かめます。
指摘してよいこと、してはいけないこと
レビューが嫌われる一番の理由は「好みを指摘されること」です。
| 指摘してよい | 指摘してはいけない |
|---|---|
| このエラーのとき落ちます | クォートはシングルのほうが好きです |
| この名前だと、中身と逆に読めます | ここは3行でなく1行で書けます(動作が同じなら) |
| この変更を戻すと、DBだけ戻りません | インデントが揃っていません |
| ここ、テストが無いので次に壊れても気づけません | 私ならこう書きます |
右の列は、人ではなく機械の仕事です。 インデントや引用符はESLintとPrettierが決めます。機械が決められることを人が指摘すると、レビューは「意見の言い合い」になります。
一人のときも同じです。 未来の自分に「好み」を書き残しても、判断材料になりません。
自分のPRは、自分でApproveできない
やってみると分かります。
GraphQL: Can not approve your own pull request (addPullRequestReview)
GitHub がそういう作りです。 これは制限ではなく、「承認は、書いた人以外がするもの」という考え方です。
なので、一人のときのレビューはこうします。
Approve ではなく Comment を使います。 「読んだ」「何を確かめた」「何を残した」を文字にして残すのが目的です。
そして、ここが後で効いてきます。⑥でブランチ保護を入れますが、「レビュー承認を必須」にすると、一人では永遠にマージできなくなります。 その設定は入れません。
⑥ ブランチ保護 — 自分が自分を止める
チェックリストは、忘れます。 忘れても止まるようにします。
やることは1つです。「CIが緑でないPRは、main にマージさせない」。
画面で設定する
- GitHub でリポジトリを開く
- Settings → 左メニューの Rules → Rulesets → New ruleset → New branch ruleset
- 名前を
protect-mainにする - Enforcement status を Active にする
- Target branches → Add target → Include default branch(=
main) - Rules で次の2つに ✅ を入れる
- Require a pull request before merging(PRを通さずに
mainへ push させない) - Require status checks to pass → Add checks で、前回作ったCIのジョブ名(
test)を選ぶ
- Create を押す
[スクリーンショット: 03_ブランチ保護.png] Ruleset の編集画面で、Require a pull request before merging と Require status checks to pass にチェックが入っている状態を撮ってください。
Require approvalsは 0 のままにしてください。 1以上にすると、自分のPRは自分で承認できない(⑤)ため、一人では絶対にマージできなくなります。
「Upgrade」と出て設定できないとき
前回作ったリポジトリを非公開にしている場合、ここで止まることがあります。 GitHub の無料プランでは、非公開リポジトリでの保護機能に制限がかかることがあるためです(GitHub の料金プランは変わるので、最新は画面の表示が正です)。
選べる道は3つです。
| 道 | やること | 向くとき |
|---|---|---|
| A. 公開にする | Settings → General → 一番下の Danger Zone → Change visibility | 秘密が1つも入っていないと確認できたときだけ |
| B. 手元で自分を止める | 下の pre-push フック | 非公開のまま続けたいとき(推奨) |
| C. 有料プランにする | — | いまは不要 |
Aは、履歴の全部が世界に見えるようになる操作です。 「いまのファイルに秘密が無い」では足りません。過去のコミットに1度でも
.envを入れたことがあるなら、公開してはいけません。 前の回で書いたとおり、消しても履歴に残ります。ついでに、セルフホストランナーを動かしているリポジトリを公開にしてはいけません。(理由はCIの回に書きました)
Bのやり方です。 Git は、特定の操作の前後に自分のスクリプトを走らせられます。これをフックと呼びます。
確かめます。
main に直接 push しようとしています。ブランチを切ってください。
どうしても必要なときだけ: git push --no-verify
error: failed to push some refs
止まりました。 空コミットは要らないので消しておきます。
フックには弱点が2つあります。 ⓵
.git/hooks/は Git の管理外なので、clone した先には付いてきません。 ⓶--no-verifyで素通りできます。それでも意味があります。 これは他人を防ぐ壁ではなく、「あ、いまブランチを切っていなかった」と気づかせる仕掛けだからです。うっかりは、これで9割止まります。
CIが落ちたPRは、本当にマージできないのか
設定は、確かめるまで信じません。わざと落とします。
テストファイルに、必ず落ちる1行を足します。
test('わざと落とす', () => {
assert.strictEqual(1, 2);
});
PRの画面を見ます。
test fail 1m2s https://github.com/.../actions/runs/...
画面では、マージボタンが灰色になり、押せません。
[スクリーンショット: 04_ci失敗でマージ不可.png] PRの下部で、チェックが赤くなり、Merge ボタンが押せなくなっている状態を撮ってください。
これが「自分が自分を止める仕組み」です。 覚えていなくても、疲れていても、深夜でも、同じように止まります。
戻します。
緑に戻れば、マージできる状態です。
git resetではなくgit revertを使いました。 push 済みの履歴にresetを使うと、強制 push(--force)が必要になります。 一人のうちはまだ被害が出ませんが、枝を共有した瞬間に、相手の履歴を壊す操作になります。 最初からrevertの癖を付けるほうが安全です。
⑦ マージして、枝を消す
3つのマージ方法があります。
| 方法 | main に残る形 | 向くとき |
|---|---|---|
| Squash and merge | PRの全コミットが1つにまとまる | ほぼこれでよい。 main の履歴が「PR1つ=1行」で読める |
| Create a merge commit | 全コミット+合流の記録が残る | 枝の中の経過も残したいとき |
| Rebase and merge | 全コミットが一直線に並ぶ | 合流の記録が邪魔なとき |
一人なら Squash が一番わかりやすいです。 枝の中の「あ、typo」「もう1回」も含めて、main には結果だけが1行で残ります。
手元も片づけます。
* main
リモートで消えた枝の情報が手元に残っていることがあります。
これで一周しました。 ブランチ → 変更 → PR → レビュー → CI → マージ → 削除。一人で、全部やりました。
⑧ レビューされやすいPRの作り方
ここは「他人のため」に見えて、一番効くのは自分です。読めないPRは、自分でもレビューできません。
1. 小さくする
行数の目安があります。 一般に、400行を超えると、指摘の見つかる率が落ちると言われます。人間の集中が続かないためです。
「小さく」は感覚ではなく、測れます。
3 files changed, 62 insertions(+), 8 deletions(-)
これが数百行になったら、分けられないかを考えます。
2. 目的を1つにする
「ついでに」を入れないということです。
| ダメなPR | 分けたPR |
|---|---|
| 「/health を足した。ついでにログの形式を変えて、ESLintの設定も直した」 | feat/health-endpoint / chore/log-format / chore/eslint-config |
理由は①と同じです。 混ざったPRは、あとから片方だけ戻せません。
3. 説明を書く
PRの説明に書くのは「何をしたか」ではありません。 それは差分に書いてあります。書くのは、差分に書けないことです。
## なぜ
監視から死活確認をしたいが、既存の `/` は DB を見ているため、
DB が重いときに監視まで巻き込まれる。
## どうした
依存を一切見ない `/health` を足した。
## 確かめたこと
- `curl localhost:3000/health` で `{"status":"ok"}` が返る
- DB を止めた状態でも 200 が返ることを確認した
## やっていないこと
- 認証は付けていない(内部からしか叩かない前提)
この4つの見出しで、だいたい足ります。 テンプレートにして、毎回出せます。
上の内容を貼って保存し、コミットして push すると、次からPR作成画面に自動で入ります。
4. 差分を汚さない
これが一番効きます。
ここに、自分が意図していない行が出ていたら、その時点でPRは読めません。 主な原因は3つです。
| 原因 | 症状 | 対処 |
|---|---|---|
| 整形と機能変更を混ぜた | ファイル全体が変更扱いになる | 整形だけのPRを先に出して、マージしてから作業する |
| 改行コードが混ざった | 変更していない行が全部出る | git config --global core.autocrlf input(Linux/Mac 側) |
| 生成物をコミットした | dist/ や node_modules/ が出る | .gitignore に入れる |
「整形だけのPR」は、レビューで中身を読みません。 「機能の変更が1行も入っていないこと」だけを確かめます。だから混ぜてはいけないのです。混ぜた瞬間、数千行の中から意味のある3行を探す作業になります。
⑨ コミットメッセージ — 「何をしたか」は書かなくていい
差分を見れば、何をしたかは分かります。 分からないのは、なぜそうしたかです。
| 悪い | よい |
|---|---|
修正 | fix: DB接続が切れたときに落ちるので再接続を入れた |
app.js を変更 | feat: 監視用に依存なしの /health を追加 |
いろいろ | (そもそも1つのコミットに「いろいろ」を入れない) |
Conventional Commits
メッセージの先頭に「種類」を付ける書き方が、広く使われています。種類: 内容 という形です。
feat: 新しい機能
fix: 不具合の修正
docs: ドキュメントだけ
style: 動作が変わらない整形
refactor: 動作を変えずに構造を直す
test: テストの追加・修正
chore: 設定やビルドまわり
利点は2つです。 ⓵ git log --oneline を眺めたときに、種類で目が滑らない。 ⓶ 機械が読めるので、リリースノートを自動生成できる。 欠点は、慣れるまで毎回どれか迷うことです。
一人なら feat / fix / docs / chore の4つだけで始めて構いません。 足りなくなってから増やします。最初から7種類を暗記しようとすると、続きません。
種類が付いているだけで、履歴の読みやすさが変わります。
⑩ ブランチ戦略 — GitHub Flow で十分
「戦略」と呼ばれていますが、要は「枝を何本立てるか」の話です。
| 枝の構成 | マージ先 | 向くとき | 一人には | |
|---|---|---|---|---|
| GitHub Flow | main + 作業枝 | 常に main | 常に最新を出す。Webサービス | これでよい |
| Git Flow | main / develop / feature / release / hotfix | 段階的 | 版を切って配るもの(インストーラ、ライブラリ) | 重すぎる |
| Trunk Based | main のみ、枝は数時間で消す | main | 1日に何度も出す大人数チーム | 枝が短命すぎて逆に難しい |
Git Flow は 2010年に提案された方式で、提案者自身が後に「Webアプリには向かない」と補足を出しています。「継続的に1つの版を出し続けるもの」には、develop と release の分だけ手間が増えるだけです。
この記事でやったのが GitHub Flow です。 ルールは5行で終わります。
mainは常に動く状態にする- 作業は必ず枝を切る
- 枝は push して、PRを作る
- CIが通ったらマージする
- マージしたら枝を消す
これ以上は、人が増えてから足せば済みます。
「人が増えたらどうするか」は、コードの分け方の話とセットになります。 サービス自体を分けるかどうかはモノリスとマイクロサービスの回で扱いました。枝の戦略を先に複雑にしても、そこは解決しません。
⑪ コンフリクトを、わざと起こして直す
コンフリクトは、初心者が一番怖がるものです。 そして怖がる理由は、初めて出会うのが「急いでいるとき」だからです。
急いでいないいま、わざと起こします。
枝を2本作って、同じ行を違う内容に変えます。
(pre-push フックを入れている場合は、ここだけ git push --no-verify を使うか、この準備も枝でやってマージしてください)
枝A:
枝B:
Aを先に main に入れます。
そのうえで、Bを入れようとします。
Auto-merging VERSION.md
CONFLICT (content): Merge conflict in VERSION.md
Automatic merge failed; fix conflicts and then commit the result.
出ました。まず、いま何が起きているかを見ます。
You have unmerged paths.
(fix conflicts and run "git commit")
(use "git merge --abort" to abort the merge)
Unmerged paths:
both modified: VERSION.md
Git は、ちゃんと出口を書いてくれています。 both modified は「両方が同じファイルを変えた」という意味です。
ファイルを開きます。
<<<<<<< HEAD
バージョン: 1.1
=======
バージョン: 2.0
>>>>>>> chore/version-b
この記号の読み方だけ覚えれば、もう怖くありません。
| 記号 | 意味 |
|---|---|
<<<<<<< HEAD | ここから下が、いま自分がいる側(=main)の内容 |
======= | 境目 |
>>>>>>> chore/version-b | ここまでが、合流させようとしている側の内容 |
Git は「どちらが正しいか」を判断できないので、両方を並べて人に渡しています。 それだけです。
直し方は、テキストを普通に編集するだけです。 記号ごと消して、残したい形にします。
バージョン: 2.0
<<<<<<<=======>>>>>>>の3行を消し忘れるのが、最も多い失敗です。消し忘れたままコミットすると、そのままコードに残ります。 保存したら必ずcatで見てください。
メッセージは Git が用意しているので、そのまま保存して構いません。
中止のしかた — これが一番大事
途中で「やっぱりやめたい」と思ったら、いつでも戻せます。
マージを始める前の状態に、完全に戻ります。 何も壊れません。
これを知っているかどうかで、コンフリクトの怖さが変わります。 「一度始めたら最後までやらないといけない」と思っていると焦ります。いつでも --abort で降りられます。
| 状況 | コマンド |
|---|---|
| マージ中に、やめたい | git merge --abort |
| いま何が衝突しているか見たい | git status |
| 片側の内容をまるごと採用したい | git checkout --ours VERSION.md / git checkout --theirs VERSION.md |
| 直したファイルを「解決済み」にする | git add <ファイル> |
--oursは「いま自分がいる枝」、--theirsは「合流させようとしている枝」です。 マージ中とリベース中で意味が入れ替わるので、迷ったら使わずに手で編集するほうが安全です。
練習用の枝を片づけます。
コンフリクトを減らす方法
技術ではなく、進め方の問題です。
- 枝を長く持たない。 3日置いた枝は、
mainから3日分ずれます - こまめに
mainを取り込む。git switch <枝>してからgit merge main - 同じファイルを触るPRを同時に開かない
- 整形と機能変更を混ぜない(⑧)。整形はファイル全体を変えるので、必ず衝突します
⑫ 置き場所は GitHub だけではない
Git はソフトウェアで、GitHub はそれを置くサービスです。(この区別は前にやりました)置き場所には他の選択肢もあります。
GitHub は、利用者数が最も多く、事実上の標準です。公開リポジトリのほとんどがここにあるので、他人のコードを読む・issue を出す・PRを送るという体験がそのまま学習になります。CI(GitHub Actions)が最初から統合されていて、この記事でやったことは全部ここで完結します。選ぶ理由に迷いがないなら、ここでよいです。
GitLab は、自分のサーバーに丸ごと立てられるのが最大の違いです(Community Edition)。ソースコードを社外に置けない組織で採用されます。CI/CD が早くから統合されていて、Auto DevOps のように「設定を書かなくても一通り回る」方向に寄っています。自前運用ができる代わりに、その運用は自分の仕事になります。
Bitbucket は、Atlassian の製品で、Jira との連携が前提にあります。「チケット番号を枝の名前に入れると、チケット側に自動で紐づく」といった動き方が標準です。すでに Jira を使っている組織で選ばれますが、それ以外の理由で選ぶことは少なくなりました。
CIツールの違いは別の回で比較しました。 置き場所を移しても、この記事でやった「枝 → PR → レビュー → マージ」は、名前が変わるだけで同じです。(GitLab では「マージリクエスト」と呼びます)
⑬ ドキュメントをどこに置くか
コードの外に置いたドキュメントは、必ず腐ります。 別の場所にあるものは、コードを直すときに一緒に直されないからです。
置き場所は、基本的に3層で考えます。
| 置き場所 | 何を書くか | 誰が読むか |
|---|---|---|
README.md | これは何か / どう動かすか / どう止めるか | 初めて開いた人(3週間後の自分を含む) |
リポジトリの中(docs/, CONTRIBUTING.md) | 設計の理由、決めごと、運用手順 | 作業する人 |
自動生成(OpenAPI、型定義、--help) | 仕様そのもの | 使う人 |
優先順位ははっきりしています。
- コードで表せることは、ドキュメントに書かない(名前を直す)
- 機械が生成できることは、手で書かない(APIの仕様は、コードから出す)
- それでも残った「なぜ」だけを、文章で書く
README.md に最低限入れるのはこれだけです。
# server
Express + MySQL の練習用API。
## 動かす
npm ci
cp .env.example .env # 値は各自で入れる
npm start
## 止める
sudo systemctl stop myserver
## 注意
- `.env` はコミットしない
- main への直接 push は禁止(PR経由)
このサイト自体も、同じことをしています。 リポジトリの直下に
CLAUDE.mdという1枚を置いて、「記事を書くときに毎回守るルール」だけを書いています。経緯や履歴は別の場所に書き、この1枚には『毎回必要なこと』しか置かない、という分け方です。ドキュメントが読まれなくなる最大の原因は、量です。
⑭ やりすぎない
ここまで書いてきましたが、一人で全部を厳密にやる必要はありません。
| 一人でもやる価値がある | 一人ならやらなくていい |
|---|---|
| ブランチを切る | レビュー承認を必須にする(そもそも不可能) |
| PRを作って、説明を書く | 複数人での相互レビュー体制 |
| CIが緑でないとマージできない設定 | develop / release 枝を作る |
| セルフレビューのチェックリスト | PRごとのラベル運用・自動割り当て |
| コミットメッセージに理由を書く | リリースノートの自動生成(後から入る) |
左の列だけでも、得られるものは大きいです。
mainが常に動く(壊れたものは入れない、が機械で保証される)- 変更の単位が「PR1つ=目的1つ」になるので、あとから1つだけ戻せる
- なぜそうしたかが、3週間後に読める
- 人が増えたときに、やり方を変えなくていい
PRは「他人に許可をもらう手続き」ではありません。 一人のときは、変更を main に入れる前に、自分で立ち止まるための場所です。立ち止まる場所があるだけで、事故は減ります。
つまずいたところ
⓵ gh pr create で「no git remote found」と言われた
~/server 以外のディレクトリで打っていました。gh は、いまいるディレクトリの Git リポジトリを見ます。 cd ~/server してから打ちます。
⓶ ブランチ保護を入れたのに、main に push できてしまった
Ruleset の Enforcement status が Disabled のままでした。 作った直後は有効になっていないことがあります。Active になっているかを必ず見てください。 また、リポジトリの管理者は「バイパス」できる設定になっていることがあります(Bypass list)。一人のときは、自分が管理者なので、ここを空にしておかないと意味がありません。
⓷ ステータスチェックの一覧に、CIのジョブ名が出てこない
GitHub は「最近走ったチェック」から候補を出します。 一度もPR上でCIが走っていないと、選べません。先にPRを1つ作ってCIを走らせてから、設定に戻ってください。
⓸ Require approvals を 1 にして、詰んだ
自分のPRは自分で承認できない(⑤)ので、マージボタンが永久に押せなくなりました。設定を 0 に戻して解決しました。 一人のときは絶対に入れない設定です。
⓹ PRの差分が2000行を超えた
エディタの設定で保存時整形が有効になっていて、触ったファイル全体の引用符とインデントが変わっていました。 一度 git checkout -- . で捨てて、整形だけのコミットを先に main に入れてから作業をやり直しました。⑧の「差分を汚さない」は、この日にできた項目です。
⓺ コンフリクトを直したのに、まだコンフリクトと言われる
git add を忘れていました。 ファイルを直しただけでは、Git には「解決した」と伝わりません。直す → git add → git commit の3手で1組です。
⓻ git branch -d が拒否された
error: The branch 'feat/x' is not fully merged.
まだマージしていない変更が残っている枝を消そうとしたときに出ます。これは親切な警告です。 本当に捨ててよいと分かっているときだけ -D(大文字)を使います。中身を確かめずに -D を打つ癖を付けないでください。
後片づけ
練習で作ったものを片づけます。
main だけになっていれば片づけ完了です。 残っている枝があれば消します。
わざと落としたテストが残っていないかを確かめます。
何も出ないのが正解です。 出たら消して、コミットしてください。
練習で作った VERSION.md が要らなければ、枝を切って消します。
この片づけ自体を、PRでやってみてください。 一周が身体に入ります。
残しておくもの:
- ブランチ保護(または
pre-pushフック) — これが本体です .github/pull_request_template.md— 次から自動で出ますREADME.md— 3週間後の自分のために
まとめ
mainに直接コミットする問題は、速さではなく「作業中のものが本番の位置にある」こと。 一人でも同じ- 混ざったコミットは、片方だけ戻せない。 分けて戻す手段は、混ぜた時点で消えている
- ブランチは「作業場所を本番から離す」ためのもの。
git switch -cで作って、git push -uで上げる - PRは Git の機能ではなく GitHub の機能。 「合流させたい」という申請であって、他人の許可を得る手続きではない
- 一人のPRは、未来の自分に向けたチェックリスト。 3週間後の自分は他人なので、「なぜ」を説明に書く
- レビューで見るのは5つだけ。 動くか / 読めるか / 戻せるか / 秘密が入っていないか / テストがあるか
- 「好み」を指摘しない。 インデントも引用符も機械の仕事。人が指摘すると意見の言い合いになる
- 自分のPRは自分でApproveできない。 だから
Require approvalsを入れると、一人では永久にマージできない - 入れるのは「ステータスチェック必須」だけでいい。 これでCIが落ちたPRは自分でもマージできない
- 設定は、わざと落として確かめる。 マージボタンが灰色になるのを見るまで、入っていると信じない
- 無料プランの非公開リポジトリで保護が使えないときは、
pre-pushフックで代替できる。 完璧ではないが、うっかりは9割止まる - 保護が使いたいからといって、非公開を公開に切り替えない。 過去のコミットは消えない
- push 済みの履歴は
resetではなくrevertで戻す。 強制 push は、枝を共有した瞬間に人を壊す - PRは小さく、目的は1つ、説明を書き、差分を汚さない。 整形と機能変更を混ぜたPRは、誰にも読めない
- コミットメッセージには「なぜ」を書く。 「何を」は差分に書いてある
- ブランチ戦略は GitHub Flow で十分。 Git Flow は版を切って配るもの向けで、一人のWebサービスには重い
- コンフリクトは、急いでいないときにわざと起こしておく。 記号3つの読み方と、
git merge --abortで降りられることを知っていれば怖くない git addを忘れると、直しても解決したことにならない- 置き場所は GitHub / GitLab / Bitbucket。 名前は変わるが、枝 → PR → レビュー → マージは同じ
- ドキュメントはコードの近くに置く。 機械が生成できることは手で書かない。 残った「なぜ」だけを書く
- 一人ならやりすぎない。 ブランチ・PR・CI必須・セルフレビューの4つで、得られるものはほとんど取れる
ここまでで、「変更を main に入れる前に立ち止まる場所」ができました。 立ち止まって何を見るかも、5項目の表になっています。あとは、それを毎回やるだけです。 そして毎回やるための仕組みは、記憶ではなくブランチ保護が持っています。
参考リンク
- GitHub Docs — プルリクエスト
- GitHub Docs — GitHub フロー
- GitHub Docs — ルールセットについて
- GitHub Docs — READMEについて
- GitHub CLI 公式サイト
- GitHub CLI マニュアル
- GitHub CLI — Linuxへのインストール手順
- Git 公式 —
git switch - Git 公式 —
git merge - Git 公式 —
git revert - Git 公式 — フック(
githooks) - Pro Git(日本語・全文無料)
- Conventional Commits 1.0.0(日本語)
- A successful Git branching model(Git Flow の原典・英語)
- GitLab 公式サイト
- Bitbucket 公式サイト
- roadmap.sh — Git and GitHub
GitHub の設定画面は改編が多く、メニューの位置がよく変わります。 「Rules」が見当たらないときは、Settings 内を 「branch」「ruleset」「protection」 で探してください。やりたいことは「
mainに入れる条件を決める」の1つです。
次に読む
この記事は 【第8段階】深掘り の 19 / 30 本目です。
| 記事 | |
|---|---|
| ← 前の記事 | 同じボタンが3種類できる理由 — デザインシステム |
| → 次の記事 | FTPは平文で流れる — 仕事で出会う古い技術 |
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。

コメント