git-workflow-and-versioning

Git Workflow and Versioning

Overview

Git is your safety net. Treat commits as save points, branches as sandboxes, and history as documentation.

Core Principles

Trunk-Based Development (Recommended)

Keep main always deployable. Work in short-lived feature branches (1-3 days).

main ──●──●──●──●──●──●──●──●──●──  (always deployable)
        ╲      ╱  ╲    ╱
         ●──●─╱    ●──╱    ← short-lived feature branches

1. Commit Policy (Single Sourced)

Commits happen when the user asked or when the repo's standing convention explicitly declares them (never silently expanded by an autonomous skill). When committing, commit clean, logical increments — don't accumulate unbounded uncommitted changes.

2. Atomic Commits

Each commit does one logical thing:

# Good: Each commit is self-contained
a1b2c3d Add task creation endpoint with validation
d4e5f6g Add task creation form component
h7i8j9k Connect form to API and add loading state

# Bad: Everything mixed together
x1y2z3a Add task feature, fix sidebar, update deps, refactor utils

3. Descriptive Messages

feat: add email validation to registration endpoint

Prevents invalid email formats from reaching the database.
Uses Zod schema validation at the route handler level.

Types: feat, fix, refactor, test, docs, chore

4. Keep Concerns Separate

Don't combine formatting changes with behavior changes. Don't combine refactors with features. Each type of change should be a separate commit.

5. Size Your Changes

~100 lines  → Easy to review, easy to revert
~300 lines  → Acceptable for a single logical change
~1000 lines → Split into smaller changes

Branching Strategy

main
  ├── feature/task-creation    ← One feature per branch
  ├── feature/user-settings    ← Parallel work
  └── fix/duplicate-tasks      ← Bug fixes

• Use the repository's intended base branch, not an assumed main.
• Keep related changes reviewable; split genuinely independent work.
• Merge, delete branches or introduce feature flags only when the task calls for them.