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. With TDD, each Red → Green → Refactor cycle produces a natural commit point.

When to Use

Always. Every code change flows through git.

Core Principles

1. Commit After Each TDD Cycle

Each successful Red → Green → Refactor cycle gets its own commit:

Write failing test (Red)
    → Make it pass (Green)
        → Refactor
            → npm test passes
                → Commit → Next cycle

2. Atomic Commits

Each commit does one logical thing:

# Good: Each commit is self-contained
a1b2c3d test: add failing test for metric calculation edge case
d4e5f6g feat: handle empty data arrays in calculateMetric
h7i8j9k refactor: extract threshold logic to utility function
m1n2o3p test: add regression test for tooltip bug #42

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

3. Descriptive Messages

<type>: <short description>

<optional body explaining why, not what>

Types:

• feat — New feature
• fix — Bug fix
• refactor — Code change that doesn't fix a bug or add a feature
• test — Adding or updating tests
• docs — Documentation only
• chore — Tooling, dependencies, config

4. Keep Concerns Separate

Don't combine formatting changes with behavior changes:

# Good: Separate concerns
git commit -m "refactor: extract data transform to shared utility"
git commit -m "feat: add confidence interval to scatter plot"

# Bad: Mixed concerns
git commit -m "refactor and add confidence interval"

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 (always deployable)
  │
  ├── feature/new-chart-type    ← One feature per branch
  ├── feature/tooltip-redesign  ← Parallel work
  └── fix/scatter-plot-crash    ← Bug fixes

• Branch from main
• Keep branches short-lived (merge within 1-3 days)
• Delete branches after merge

Branch Naming

feature/<short-description>   → feature/box-plot-module
fix/<short-description>       → fix/bar-chart-null-data
chore/<short-description>     → chore/update-chartjs
refactor/<short-description>  → refactor/data-pipeline

The TDD Save Point Pattern

Agent starts work
    │
    ├── Writes failing test (Red)
    │   ├── Implements code (Green) → Refactors → Tests pass? → Commit
    │   └── Tests fail unexpectedly? → git reset --hard HEAD → Investigate
    │
    ├── Writes next failing test (Red)
    │   ├── Implements → Green → Refactor → Commit
    │   └── Tests fail? → Revert to last commit → Investigate
    │
    └── Feature complete → Clean history of TDD cycles

Pre-Commit Hygiene

Before every commit:

# 1. Check what you're about to commit
git diff --staged

# 2. Run tests
npm test

# 3. Verify build
npm run bundle

# 4. Ensure no secrets
git diff --staged | grep -i "password\|secret\|api_key\|token"

Change Summaries

After any modification, provide a structured summary:

CHANGES MADE:
- src/scatterPlot/config.js: Added threshold line support
- tests/scatterPlot.test.js: Added TDD tests for threshold line

THINGS I DIDN'T TOUCH (intentionally):
- src/barChart/: Has similar gap but out of scope
- src/util/colors.js: Could use refactoring (separate task)

TDD EVIDENCE:
- Failing tests written before implementation
- All tests pass: npm test
- Build succeeds: npm run bundle

Common Rationalizations

Red Flags

• Large uncommitted changes accumulating
• Commit messages like "fix", "update", "misc"
• No evidence of TDD in commit history (no test commits before implementation commits)
• Formatting changes mixed with behavior changes
• Committing node_modules/, .env, or build artifacts

Verification

For every commit:

• Commit does one logical thing
• Message explains the why, follows type conventions
• Tests pass before committing: npm test
• Build succeeds: npm run bundle
• No secrets in the diff
• .gitignore covers standard exclusions

Source: Gilead-BioStats/gsm.viz — distributed by TomeVault.