Files
praxis/docs/03-git-workflow.md
T
阿白叔andClaude Opus 4.7 411f0b8182 docs: add Chinese README and dated-tag versioning rules
- Move English README to README.en.md, add Chinese README.md as the entry point
- Cross-link both READMEs at the top
- Add Tagging section to docs/03-git-workflow.md (YYYYMMDD format,
  immutable, annotated, daily-suffix collisions)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 09:22:38 +08:00

4.4 KiB

03 — Git workflow

Small team, light process. Branches, commits, PRs, review.

Branches

  • main is always shippable. No direct pushes. No exceptions.
  • Feature branches: <owner>/<short-slug> — e.g. bai/auth-retry, bai/eval-agent-rerun. Lowercase, hyphens, your handle as prefix.
  • Long-lived integration branches: integration/<topic> — only with team agreement.
  • Delete branches after merge. Old branches confuse search.

Commits

Format:

<area>: <imperative summary under 60 chars>

<optional body — what changed and why, not how>
  • <area> 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.

Tagging (versioning)

We tag by date: YYYYMMDD (e.g. 20260520). Each tag is a snapshot of main worth pointing at — "this is the version we agreed to follow."

Rules:

  • Tag only on main. Tagging a feature branch is a smell.
  • One tag per day max. If you cut a second one the same day, suffix with -N: 20260520-2, 20260520-3.
  • Tag messages are annotated, not lightweight. Use git tag -a and write one or two sentences about what changed since the last tag.
  • A tag, once pushed, is immutable. No deleting, no moving, no force-tag. If the tag is wrong, cut a new one.
  • Tag the commit, push the tag, and announce the tag name. That's the release.

Cut a tag:

git checkout main
git pull --ff-only
git tag -a 20260520 -m "team-guide 20260520: bilingual README, dated tags"
git push origin 20260520

List / inspect:

git tag --sort=-creatordate           # newest first
git show 20260520                     # show what's in a tag
git log --oneline 20260513..20260520  # what changed between tags

When to cut a tag:

  • The docs in this repo changed in a way teammates need to read.
  • A template was added, removed, or restructured.
  • A new convention is now in effect (not just proposed).

When NOT to cut a tag:

  • Typo fixes, formatting, broken links → just push to main.
  • Drafts under discussion → use a PR, don't tag.

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 deleting or moving tags after they've been pushed. Cut a new one instead.
  • 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.