tomevault-io 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/, orchore/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
Source: kid-sid/codex-spellbook — distributed by TomeVault.