107 lines
6.6 KiB
Markdown
107 lines
6.6 KiB
Markdown
# Ticket lifecycle commit の配置ミス
|
|
|
|
日付: 2026-05-10
|
|
|
|
## 要旨
|
|
|
|
今回の `memory-usage-metrics` の review / merge workflow では、ticket lifecycle の状態遷移 commit を feature branch ではなく `develop` 側に作ってしまった。実装 branch を merge する前に review artifact 作成と ticket 完了削除を行う、という順序だけでなく、「その操作をどの branch / worktree で行うか」を workflow が強制・確認できていないことが問題だった。
|
|
|
|
## 今回起きたこと
|
|
|
|
`memory-usage-metrics` の実装 branch を review した後、親 worktree で以下を行った。
|
|
|
|
1. `tickets/memory-usage-metrics.review.md` を作成
|
|
2. `tickets/memory-usage-metrics.md` にレビュー状態を追記
|
|
3. `develop` に merge
|
|
|
|
その後、完了時には `.review.md` と ticket 本体を消す必要がある、という指摘を受けて、いったん merge を巻き戻して以下の順序に直した。
|
|
|
|
1. review commit
|
|
2. ticket / review / TODO 削除 commit
|
|
3. merge commit
|
|
|
|
しかし、この修正も `develop` 側で review commit と ticket 完了 commit を作っており、feature branch 側の lifecycle としては不正だった。最終的には、これらの commit を `memory-usage-metrics` branch に移し、`develop` は feature branch を merge するだけの形に直した。
|
|
|
|
最終形は次のようになった。
|
|
|
|
```text
|
|
* merge: memory usage metrics # develop
|
|
|\
|
|
| * docs(tickets): complete memory usage metrics
|
|
| * review: memory usage metrics
|
|
| * feat: add memory usage event metrics # memory-usage-metrics
|
|
|/
|
|
* docs(tickets): complete memory phase naming cleanup
|
|
```
|
|
|
|
## 障壁
|
|
|
|
### 1. Ticket lifecycle の「順序」と「配置」が別々に失敗しうる
|
|
|
|
現行 lifecycle は、作成・レビュー・完了を commit の履歴で表現する。ただし、守るべき制約は少なくとも二つある。
|
|
|
|
- review commit の後に completion commit を置く
|
|
- それらを対象 ticket の作業 branch 側に置く
|
|
|
|
今回、最初の修正では前者だけを直し、後者を落とした。workflow の説明や自分のチェック観点が「merge 前に `.review.md` を消す」へ寄りすぎており、「それを向こうの branch でやる」という branch placement を明示的な検査項目にしていなかった。
|
|
|
|
### 2. 親 worktree で操作していると lifecycle commit を `develop` に作りやすい
|
|
|
|
reviewer / orchestrator は親 worktree にいることが多い。そこで ticket file を編集すると、自然に `develop` 上の変更になる。
|
|
|
|
一方で、このプロジェクトの運用では ticket / review artifact も feature branch の成果物として扱うべきで、`develop` の first-parent に review や ticket 完了 commit が直接並ぶのは望ましくない。親 worktree でレビュー文面を作ること自体は可能でも、commit 先は feature branch worktree でなければならない。
|
|
|
|
### 3. Git 履歴の見え方を確認するタイミングが遅かった
|
|
|
|
`git log --graph` は確認したが、最初は「merge commit ができたか」「ticket が消えているか」を見ており、first-parent 上に lifecycle commit が混ざっていないかを確認していなかった。
|
|
|
|
この問題は `git log --first-parent --oneline` を merge 前後に見るだけで早期に検出できる。feature branch workflow では、merge 前の `develop` first-parent に review / completion commit が増えていたら誤りである。
|
|
|
|
### 4. 無関係な `AGENTS.md` 変更を commit に巻き込みかけた
|
|
|
|
review commit 作成時に、既存の unrelated な `AGENTS.md` 変更を一度 commit に含めてしまい、soft reset で修正した。これは branch placement とは別問題だが、同じ workflow の中で起きた安全確認不足である。
|
|
|
|
`git add` の対象を明示しても、既に index に入っている unrelated change があると混入しうる。作業前に `git status --short` だけでなく `git diff --cached --stat` を確認する必要がある。
|
|
|
|
## 影響
|
|
|
|
- `develop` の first-parent に、feature branch 内で完結すべき review / ticket 完了 commit が直接混ざる
|
|
- ticket lifecycle の履歴を辿る時に、対象 branch の作業としてまとまって見えない
|
|
- merge 前後の状態遷移が曖昧になり、後から履歴を直すために reset / cherry-pick / re-merge が必要になる
|
|
- unrelated change の混入リスクが上がる
|
|
|
|
## 暫定運用
|
|
|
|
feature branch の ticket を review / complete するときは、次を標準手順にする。
|
|
|
|
1. 親 worktree ではなく対象 branch worktree に移動する
|
|
2. `git status --short --branch` で現在 branch を確認する
|
|
3. review artifact を作成し、ticket にレビュー状態を追記して commit する
|
|
4. completion として ticket / review / TODO を削除して commit する
|
|
5. 親 worktree の `develop` に戻り、対象 branch を merge する
|
|
6. `git log --first-parent --oneline -5` で `develop` first-parent に lifecycle commit が直接載っていないことを確認する
|
|
7. `git status --short` と `git diff --cached --stat` で unrelated change が混ざっていないことを確認する
|
|
|
|
## 改善案
|
|
|
|
### A. Workflow checklist に branch placement を明記する
|
|
|
|
「レビューを書いたか」「ticket を消したか」だけでは足りない。ticket lifecycle commit は対象 branch に置く、という項目を review / merge workflow の checklist に入れる。
|
|
|
|
### B. Merge 前検査をコマンド化する
|
|
|
|
merge 前に以下を確認する小さな doctor / script があるとよい。
|
|
|
|
- current branch が `develop` か
|
|
- feature branch 側に `.review.md` 作成 commit と ticket completion commit があるか
|
|
- `develop` first-parent が merge base から進んでいないか、または進んでいる場合は意図した mainline commit だけか
|
|
- index に unrelated staged changes がないか
|
|
|
|
### C. Ticket lifecycle 操作用の workflow を作る
|
|
|
|
review artifact 作成、ticket 状態追記、completion deletion、merge 前 first-parent 確認を一つの workflow としてまとめると、手順の抜けが減る。特に branch/worktree の切り替えを workflow 側が明示的に促すだけでも効果がある。
|
|
|
|
## 現時点の判断
|
|
|
|
今回の問題は Git 操作ミスというより、file-based ticket lifecycle を branch workflow に載せる時の検査不足である。今後は「どの順序で状態遷移したか」だけでなく、「どの branch に状態遷移 commit を置いたか」を first-class な確認項目にする必要がある。
|