# 03 — Git workflow Small team, light process. Branches, commits, PRs, review. ## Branches - `main` is always shippable. No direct pushes. No exceptions. - Feature branches: `/` — e.g. `bai/auth-retry`, `bai/eval-agent-rerun`. Lowercase, hyphens, your handle as prefix. - Long-lived integration branches: `integration/` — only with team agreement. - Delete branches after merge. Old branches confuse search. ## Commits Format: ``` : ``` - `` is a directory or component, lowercase: `eval-agent`, `task_assistant`, `docs`, `git-workflow`. - Imperative: "add", "fix", "rename" — not "added" / "adding". - Body wraps at ~72 chars. Skip it for trivial commits. - One topic per commit. "and" in the summary means split it. - AI-assisted commits get the `Co-Authored-By` trailer Claude Code adds by default. Don't strip it. Examples: ``` eval-agent: rerun failed tasks with stable seed docs: clarify branch naming in git-workflow task_assistant: drop unused legacy export path ``` ## Pull requests - One PR per topic. If you can't describe it in one sentence, it's multiple PRs. - Title under 70 chars, same shape as a commit summary. - Description uses `templates/PR_DESCRIPTION.template.md`. - Push to your feature branch with `-u` the first time so it tracks remote. - Open the PR as soon as you have something runnable, even if it's a draft. Review-as-you-go beats review-at-the-end. ## Review We review every PR before merge, even our own AI-assisted ones. Reviewer checks: 1. Does the description match the diff? If the diff has surprises, ask. 2. Read every file changed. If a file isn't related to the stated topic, ask why it's in the PR. 3. Run the change locally if it's not obviously correct from reading. 4. New deps, schema changes, env vars, or auth-touching code → block until justified. 5. Comment on the *least* important issue first; save the merge-blocker for last so it's clearly the gate. Author follow-ups: - Address every comment, even with "agreed, fixed in ". - If you disagree, push back in writing. Don't silently ignore. - Squash fixup commits before merge if the history is noisy. ## Merging - Squash for feature branches. Merge commits are reserved for integration branches. - Final squash message follows the commit format above. The PR title is usually the right starting point. - Delete the branch on merge. ## What NOT to do - No `git push --force` to `main`. Period. To your own branch, only if nobody else has pulled it. - No `--no-verify` to skip hooks. Fix what the hook is complaining about. - No amending pushed commits. Once it's on the remote, add a new commit. - No committing `.env`, credentials, or files larger than ~5 MB without a Git LFS conversation first. - No staging with `git add .` or `git add -A` when there are untracked files you don't recognize. Stage by name.