git-workflow

name	git-workflow
description	Git workflow guidance for branch naming, conventional commits, PR title format, merge strategy, and safe history rewriting. Use when creating branches, preparing commits, or reviewing repository hygiene.

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

• Branch name matches feat/, fix/, or chore/ intent
• Commit subject uses a conventional commit type
• Commit body explains why the change exists when context is non-trivial
• PR title matches commit style
• Merge strategy fits the branch history
• Shared history is never force-pushed without --force-with-lease
• Review fixups are squashed or left intentionally