paulund/git-workflow-and-versioning

Core Workflow

1. Trunk-based development

Keep main always deployable. Work in short-lived feature branches that merge back within 1–3 days. Long-lived branches are hidden costs — they diverge, create conflicts, and delay integration. Prefer feature flags over long-lived branches for incomplete features.

2. Commit discipline

• Atomic commits — each commit does one logical thing
• Early and often — commit at every successful increment: implement slice → test → verify → commit → next slice
• Descriptive messages — explain the why, not the what:

  feat: add email validation to registration endpoint
  
  Prevents invalid email formats from reaching the database.
  Uses Zod schema validation at the route handler level,
  consistent with existing patterns in auth.ts.
  

  Types: feat, fix, refactor, test, docs, chore
• Separate concerns — formatting changes and behaviour changes are separate commits; refactors and features are separate commits

3. Branch naming

feature/<short-description>   →  feature/task-creation
fix/<short-description>       →  fix/duplicate-tasks
chore/<short-description>     →  chore/update-deps
refactor/<short-description>  →  refactor/auth-module

4. Pre-commit hygiene

Before every commit:

git diff --staged                                               # Review what you're about to commit
git diff --staged | grep -i "password\|secret\|api_key\|token" # No secrets
npm test && npm run lint                                        # Tests and lint pass

5. Worktrees for parallel agent work

Create isolated worktrees so multiple agents can work on different branches simultaneously without interfering:

git worktree add ../project-feature-a feature/task-creation
git worktree add ../project-feature-b feature/user-settings

# When done, merge/push then clean up:
git worktree remove ../project-feature-a

Each worktree has its own working directory and branch. If an experiment fails, delete the worktree — nothing is lost.

6. Save-point pattern

After each successful increment, commit immediately. If the next change breaks something, git reset --hard HEAD restores the last known-good state instantly. Never accumulate large uncommitted changes.

7. Change summary format

After any modification, provide a structured summary:

CHANGES MADE:
- src/routes/tasks.ts: Added validation middleware to POST endpoint
- src/lib/validation.ts: Added TaskCreateSchema using Zod

THINGS I DIDN'T TOUCH (intentionally):
- src/routes/auth.ts: Has a similar validation gap — out of scope for this task

POTENTIAL CONCERNS:
- Zod schema is strict and rejects extra fields. Confirm this is desired.

Common Rationalizations

| Rationalization | Reality | |---|---| | "I'll commit when the feature is done" | One giant commit is impossible to review, debug, or revert. Commit each slice. | | "The message doesn't matter" | Messages are documentation. Future agents will need to understand what changed and why. | | "I'll split this change later" | Large changes are harder to review and riskier to deploy. Split before submitting, not after. | | "Branches add overhead" | Short-lived branches are free. Long-lived branches are the problem — merge within 1–3 days. |

Red Flags

• [ ] Large uncommitted changes accumulating
• [ ] Commit messages like "fix", "update", "wip", "misc"
• [ ] Formatting changes mixed with behaviour changes in one commit
• [ ] Refactoring mixed with feature work in one commit
• [ ] No .gitignore in the project
• [ ] Long-lived branches diverging significantly from main
• [ ] Force-pushing to shared branches

Verification

For every commit:

• [ ] Commit does one logical thing
• [ ] Message explains the why and follows type conventions
• [ ] Tests pass before committing
• [ ] No secrets in the diff
• [ ] No formatting-only changes mixed with behaviour changes
• [ ] .gitignore covers standard exclusions (node_modules/, .env, build artifacts)

Constraints

MUST DO

• Commit at every successful increment — never accumulate large uncommitted changes.
• Use type-prefixed commit messages (feat:, fix:, refactor:, etc.).
• Run tests and check for secrets before every commit.
• Use worktrees when running multiple parallel agent sessions on different branches.

MUST NOT DO

• Force-push to shared branches.
• Mix formatting changes with behaviour changes in one commit.
• Commit .env, node_modules/, or build output.
• Squash the development history into one commit after the fact.