Git workflow
Git is an auditable change history, not just backup. This page fixes default branch names, commit messages, PRs, and release tags so personal repos and shared projects share the same habits.
Branch model (default)
| Branch | Purpose | Merges into |
|---|---|---|
main | Deployable/stable line | — |
feature/* | Single feature or fix | main via PR |
fix/* | Hotfix (optional) | main + cherry-pick if needed |
release/* | Version freeze (optional) | main + tag |
Solo repos: small commits on main are fine; spin feature/* when scope grows.
Short-lived branches: prefer < 3 days to limit merge pain. Daily git fetch and rebase or merge onto latest main—pick one per team and stick to it.
Commit messages
Use a Conventional Commits subset for changelogs and semver:
<type>(<scope>): <subject>
<optional body>
| type | Meaning |
|---|---|
feat | New capability |
fix | Bug fix |
docs | Docs only |
refactor | No behavior change |
test | Tests |
chore | Build, deps, misc |
subject: imperative, ≤72 chars, no trailing period; state what changed, not a novel.
Pull request checklist
- Single scope: one problem per PR
- CI green: lint, tests, contracts if any
- Description: why, approach, how to verify, linked issues
- Breaking changes labeled
BREAKINGin title or body - Large diffs include migration/architecture notes
Review for: boundary crossings, behavioral test coverage, easy rollback—see boundaries.
Merge strategies
| Strategy | Upside | Caveat |
|---|---|---|
| Squash | Clean main | Loses fine commits; PR title matters |
| Rebase | Linear history | Never rewrite pushed shared branches |
| Merge commit | Preserves topology | Noisier graph |
Default: squash for product main; merge commits when preserving contributor history (OSS).
Tags and release
| Tag | Meaning |
|---|---|
vMAJOR.MINOR.PATCH | Semver |
v1.2.3-rc.1 | Pre-release |
Short release path:
- Tag
mainand push - CI builds artifacts / images / store build numbers
- Attach release notes (from conventional commits if possible)
Hygiene and security
- No secrets or local
.envoverrides in git; document vars in.env.example .gitignoresensitive paths; rotate credentials after accidental commit;git filter-repoonly with care on shared branches- Optional signed commits (GPG/SSH) for supply-chain assurance