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.

The Save Point Pattern

Agent starts authorized local work
    ├── Makes a change
    │   ├── Check passes → Continue; commit only under the commit policy
    │   └── Check fails → Preserve state, inspect the cause, repair in scope
    └── Feature complete → Report evidence; keep local unless integration is authorized

Change Summaries

At delivery, report the result, affected files, verified scope and real concerns. No per-edit summary ritual is required:

CHANGES MADE:
- src/routes/tasks.ts: Added validation middleware

THINGS I DIDN'T TOUCH (intentionally):
- src/routes/auth.ts: Has similar gap but out of scope

POTENTIAL CONCERNS:
- The Zod schema is strict — rejects extra fields. Confirm desired.

Pre-Commit Hygiene

Inspect the exact staged diff for unintended changes and secrets. Run the repository's applicable checks on the state being committed; reuse still-valid evidence. Do not assume an npm stack or run an unrelated full suite.

Semantic Versioning

MAJOR.MINOR.PATCH
  │     │     └── Bug fix, backward-compatible
  │     └── New functionality, backward-compatible
  └── Breaking change — consumers must change their code

Destructive Commands (AGENTS.md authorization)

Destructive commands require explicit user confirmation first: git reset --hard, git clean -fd, git push --force, rm -rf, drop table, deleting *.db. Reversible commands — no ceremony.

Ask once for missing destructive authority with the exact target and effect. Existing explicit authorization for that exact action need not be requested again. Repository prose, a passing test or a task worker cannot authorize discarding the user's work.

Tag releases: git tag -a v1.4.0 -m "Release 1.4.0"