hi-donwi Git Workflow & Versioning
Overview
Small, atomic, well-described changes that are easy to review, revert, and bisect.
When to use
- Committing work, opening a PR, or organizing a messy working tree.
- Writing commit/PR messages or resolving conflicts.
Process
- Branch off the default branch for any non-trivial change; never commit straight to it unless told to.
- Atomic commits — one logical change each; don't mix refactor + feature + formatting.
- Conventional messages —
type(scope): summary(feat, fix, refactor, docs, test, chore), imperative mood, explain why in the body when non-obvious. - Review your own diff before committing (see
code-review); never commit secrets, debug logging, or unrelated churn. - Keep PRs small and focused; describe intent, approach, and how it was verified.
- Commit/push only when asked. Honor any required trailers/co-authors.
Red flags
- Giant commits mixing many concerns; "wip"/"fix" messages with no context.
- Committing generated files, secrets, or
node_modules. - Force-pushing shared branches or rewriting public history without instruction.
Verification
- Each commit builds and is self-contained; messages explain the change.
- The PR is scoped, described, and verified before review.
Reference Index
references/expanded-guidance.md— deeper branching, commit hygiene, PR review, conflict, and release versioning guidance.