- 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>
4.4 KiB
4.4 KiB
03 — Git workflow
Small team, light process. Branches, commits, PRs, review.
Branches
mainis 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-Bytrailer 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
-uthe 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:
- Does the description match the diff? If the diff has surprises, ask.
- Read every file changed. If a file isn't related to the stated topic, ask why it's in the PR.
- Run the change locally if it's not obviously correct from reading.
- New deps, schema changes, env vars, or auth-touching code → block until justified.
- 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 -aand 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 --forcetomain. Period. To your own branch, only if nobody else has pulled it. - No
--no-verifyto 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 .orgit add -Awhen there are untracked files you don't recognize. Stage by name.