Git Workflow and Versioning
Overview
Use trunk-based development with atomic commits. Keep changes small, write clear commit messages, and treat every commit as a save point that could be deployed independently.
When to Use
- Every code change, without exception
Core Principles
Trunk-Based Development
- Work on short-lived feature branches
- Merge to main frequently (at least daily)
- Keep branches small and focused
- Use feature flags for incomplete work
Atomic Commits
Each commit should:
- Contain one logical change
- Leave the codebase in a buildable, testable state
- Be revertable without breaking other work
Change Sizing
- Target ~100 lines per change for easy review
- Maximum ~400 lines unless the change is mechanical (renames, generated code)
- If a change is too large, break it into smaller sequential commits
Commit-as-Save-Point
Treat each commit as a checkpoint:
- All tests pass at each commit
- The system is deployable at each commit
- Each commit message explains what and why
Commit Message Format
type: short description (50 chars max)
- What changed
- Why it changed
- Any relevant context
Refs: #issue-number
Types: feat, fix, refactor, docs, test, chore, perf, ci
Process
Step 1: Create Feature Branch
git checkout -b feat/short-description main
Step 2: Make Atomic Commits
- Stage related changes together
- Write a clear commit message
- Run tests before committing
- Push after each meaningful milestone
Step 3: Keep Branch Up to Date
git fetch origin main
git rebase origin/main
Resolve conflicts promptly. Do not let branches diverge for days.
Step 4: Create Pull Request
- Write a clear description of what changed and why
- Include a test plan
- Keep PRs small enough for thorough review
Common Rationalizations
| Rationalization |
Reality |
| "I will commit everything at the end" |
A single large commit is hard to review, hard to revert, and loses intermediate context. |
| "WIP commits are fine, I will squash later" |
If you squash, you lose the save points. If you don't, you merge messy history. |
| "This change is too small for its own commit" |
Small changes are exactly what make good atomic commits. |
Verification
Anti-Rationalization Table
| Excuse |
Counter |
| "I'll commit everything at the end" |
A single large commit is hard to review, hard to revert, and loses intermediate context. |
| "WIP commits are fine, I'll squash later" |
If you squash, you lose the save points. If you don't, you merge messy history. |
| "This change is too small for its own commit" |
Small changes are exactly what make good atomic commits. |
| "I'll rebase later when the branch is done" |
Letting branches diverge creates painful merge conflicts. Rebase frequently. |
| "Feature flags are overkill for this" |
Feature flags enable merging incomplete work safely. They prevent long-lived branches. |
1---2name: git-workflow-and-versioning3description: Trunk-based development, atomic commits, change sizing (~100 lines), commit-as-save-point pattern. Use when making any code change.4---56# Git Workflow and Versioning78## Overview910Use trunk-based development with atomic commits. Keep changes small, write clear commit messages, and treat every commit as a save point that could be deployed independently.1112## When to Use1314- Every code change, without exception1516## Core Principles1718### Trunk-Based Development1920- Work on short-lived feature branches21- Merge to main frequently (at least daily)22- Keep branches small and focused23- Use feature flags for incomplete work2425### Atomic Commits2627Each commit should:28- Contain one logical change29- Leave the codebase in a buildable, testable state30- Be revertable without breaking other work3132### Change Sizing3334- Target ~100 lines per change for easy review35- Maximum ~400 lines unless the change is mechanical (renames, generated code)36- If a change is too large, break it into smaller sequential commits3738### Commit-as-Save-Point3940Treat each commit as a checkpoint:41- All tests pass at each commit42- The system is deployable at each commit43- Each commit message explains what and why4445## Commit Message Format4647```48type: short description (50 chars max)4950- What changed51- Why it changed52- Any relevant context5354Refs: #issue-number55```5657Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`5859## Process6061### Step 1: Create Feature Branch6263```bash64git checkout -b feat/short-description main65```6667### Step 2: Make Atomic Commits6869- Stage related changes together70- Write a clear commit message71- Run tests before committing72- Push after each meaningful milestone7374### Step 3: Keep Branch Up to Date7576```bash77git fetch origin main78git rebase origin/main79```8081Resolve conflicts promptly. Do not let branches diverge for days.8283### Step 4: Create Pull Request8485- Write a clear description of what changed and why86- Include a test plan87- Keep PRs small enough for thorough review8889## Common Rationalizations9091| Rationalization | Reality |92|---|---|93| "I will commit everything at the end" | A single large commit is hard to review, hard to revert, and loses intermediate context. |94| "WIP commits are fine, I will squash later" | If you squash, you lose the save points. If you don't, you merge messy history. |95| "This change is too small for its own commit" | Small changes are exactly what make good atomic commits. |9697## Verification9899- [ ] Each commit is one logical change100- [ ] Tests pass at each commit101- [ ] Commit messages follow the format102- [ ] Branch is up to date with main103- [ ] PR description includes test plan104105## Anti-Rationalization Table106107| Excuse | Counter |108|--------|---------|109| "I'll commit everything at the end" | A single large commit is hard to review, hard to revert, and loses intermediate context. |110| "WIP commits are fine, I'll squash later" | If you squash, you lose the save points. If you don't, you merge messy history. |111| "This change is too small for its own commit" | Small changes are exactly what make good atomic commits. |112| "I'll rebase later when the branch is done" | Letting branches diverge creates painful merge conflicts. Rebase frequently. |113| "Feature flags are overkill for this" | Feature flags enable merging incomplete work safely. They prevent long-lived branches. |
v1truv1us