Git Workflow
Keep history readable, reviewable, and safe for collaborators by using consistent branch names, conventional commits, and disciplined merge behavior.
When to Activate
- Start a new feature or fix branch
- Prepare commits before opening a PR
- Rename a noisy branch before review
- Decide whether to squash or merge
- Rewrite branch history after review feedback
- Audit commit hygiene before release
- Recover from a mistaken push safely
Branch Naming
| Change Type |
Pattern |
Example |
| Feature |
feat/<topic> |
feat/api-pagination |
| Fix |
fix/<topic> |
fix/jwt-expiry-check |
| Chore |
chore/<topic> |
chore/update-ci |
Conventional Commits
| Type |
Use When |
feat: |
User-visible capability added |
fix: |
Bug fixed |
docs: |
Documentation only |
chore: |
Maintenance with no product behavior change |
refactor: |
Structure changed without behavior change |
test: |
Tests added or updated |
perf: |
Measurable performance improvement |
feat(api): add cursor pagination to list users
Why:
- offset scans were timing out on large tenants
What:
- added cursor token parsing
- exposed page.has_more
Pull Requests and Merge Strategy
| Field |
Format |
| PR title |
<type>(<scope>): <summary> |
| Description |
problem, approach, risks, validation |
| Linked work |
issue or ticket reference when available |
| Situation |
Preferred |
Avoid |
| Small feature branch |
Squash merge |
Preserving noisy fixup history |
| Multi-commit change with meaningful milestones |
Merge commit |
Squashing away useful audit trail |
| Local cleanup before review |
Rebase locally |
Rewriting shared branch unexpectedly |
Safe Rewrites
| Operation |
Rule |
| Rewrite your own reviewed branch |
Use --force-with-lease |
| Rewrite shared branch used by others |
Do not do it without explicit coordination |
| Recover from mistaken push |
Prefer revert when branch is public |
BAD
commit message: stuff
branch: new-branch
GOOD
commit message: fix(auth): reject expired refresh tokens
branch: fix/refresh-token-expiry
Checklist