Version Control

Why Version Control matters for Data Visualization Engineers

Version control is your safety net and collaboration engine. Visualizations combine code (SQL, Python, JS/D3), design assets (SVG, images, CSS), BI files, and data snapshots. With Git done right, you can: work in branches without breaking production dashboards, review changes safely, trace when a number changed, reproduce a release, and automate checks that catch issues before they reach stakeholders.

What you will be able to do

• Set up clean repos for visualization work with sensible .gitignore and project structure.
• Use branches and pull requests to ship features and bugfixes safely.
• Track large assets and data snapshots appropriately (including Git LFS).
• Run CI checks to lint JSON/CSV, build charts, and prevent regressions.
• Create tagged releases so any figure or dashboard is reproducible.
• Resolve merge conflicts quickly and review code with confidence.

Who this is for

• Data Visualization Engineers building dashboards, explorable articles, or chart libraries.
• BI developers who need safe collaboration on reports, metrics, and visuals.
• Analysts transitioning from notebooks to production-grade visualization workflows.

Prerequisites

• Basic command line comfort (cd, ls, mkdir).
• Familiarity with at least one tool you version: SQL, Python notebooks, or JS/D3.
• Ability to read JSON/CSV and simple config files (YAML/INI).

Learning path

1. Git basics for viz projects: init, clone, status, add, commit, log; set up .gitignore and a clean structure.
2. Branching and PRs: feature branches, push, review, squash/merge safely.
3. Manage assets & data: Git LFS for large files; store canonical small samples; ignore generated artifacts.
4. Code reviews: small PRs, check visuals, data diffs, and performance impact.
5. Releases & tags: semantic tags (v1.2.0), release notes, reproducible builds.
6. Merge conflicts: practice resolving conflicts in JSON, CSS, and notebooks.
7. CI basics: automate linting, data schema checks, and chart builds.
8. Documentation: README, contribution guide, decision records.

Worked examples

# 1) Initialize
git init viz-project
cd viz-project

# 2) Minimal structure
mkdir -p src/js src/css src/img data scripts dist

# 3) .gitignore (keep repo lean)
cat > .gitignore << 'EOF'
# OS + editors
.DS_Store
*.swp

# Environments
.env
.venv/
node_modules/

# Builds and caches
dist/
__pycache__/
*.ipynb_checkpoints

# BI/large binaries kept outside core source or tracked via LFS if needed
*.pbix
*.twbx
EOF

# 4) First commit
git add .
git commit -m "chore: init project structure and .gitignore"

# Create feature branch
git checkout -b feat/map-legend

# Edit files, then commit
git add src/js/legend.js src/css/legend.css
git commit -m "feat(legend): add categorical legend with color scale"

# Push branch
git push -u origin feat/map-legend

# Open a PR in your Git platform, request review, address feedback
# After approval:
# Option A: Squash and merge to main
# Option B: Merge commit with a clean history

# Install and configure LFS once per machine
git lfs install

# Track large file patterns
git lfs track "*.csv"
git lfs track "*.parquet"
git lfs track "*.png"

# Ensure attributes are committed
git add .gitattributes

# Commit large assets as needed
git add data/sample_100k.csv src/img/hero.png
git commit -m "chore: track large CSV and PNG via LFS"

*.csv filter=lfs diff=lfs merge=lfs -text
*.parquet filter=lfs diff=lfs merge=lfs -text
*.png filter=lfs diff=lfs merge=lfs -text

{
  "title": "Sales by Region",
  <<<<<<< HEAD
  "colorScheme": "blues",
  =======
  "colorScheme": "greens",
  >>>>>>> feat/new-colors
  "showLegend": true
}

# After fixing the file
git add src/config/chart.json
git commit -m "fix: resolve colorScheme conflict to greens"

# Update CHANGELOG.md and ensure main is green

# Create annotated tag
git tag -a v1.1.0 -m "v1.1.0: added legend, improved color scale"

# Push tag
git push origin v1.1.0

## v1.1.0 (YYYY-MM-DD)
- Feature: Map legend (PR #123)
- Change: Color scale tuned for accessibility
- Data: Snapshot data/sales_2024-03-01.csv (LFS)
- Build: Chart build hash abc123
- Rollback: git checkout v1.0.0

name: checks
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Node
        run: |
          node -v || true
      - name: Install JS deps
        run: |
          [ -f package.json ] && npm ci || echo "no package.json"
      - name: Lint JSON
        run: |
          npx --yes jsonlint-cli "src/**/*.json" -q || echo "no json to lint"
      - name: Validate CSV headers
        run: |
          python - <<'PY'
import csv, sys, glob
required = {"region","sales","date"}
for path in glob.glob('data/*.csv'):
    with open(path, newline='') as f:
        headers = set(next(csv.reader(f)))
        missing = required - headers
        if missing:
            print(f"Missing {missing} in {path}")
            sys.exit(1)
print("CSV headers OK")
PY
      - name: Build charts
        run: |
          [ -f package.json ] && npm run build || echo "no build step"

Drills and quick exercises

• [ ] Initialize a repo with src/, data/, scripts/, and dist/ folders.
• [ ] Add a .gitignore tailored to your tools and OS.
• [ ] Create a feature branch, make two commits, and push.
• [ ] Open a PR with a concise description and screenshots of the visual change.
• [ ] Configure Git LFS for .csv and .png, commit one of each.
• [ ] Simulate a merge conflict on a JSON file and resolve it.
• [ ] Create an annotated tag v0.1.0 and push it.
• [ ] Add a CI step that lints JSON files.
• [ ] Write a README with run, build, and data notes.
• [ ] Add a CONTRIBUTING guide with review checklist.

Common mistakes and debugging tips

Mini project: Reproducible micro-dashboard

Build a tiny but production-like setup that touches all subskills.

1. Create repo structure: src/js, src/css, data, scripts, dist.
2. Add a small CSV (sales_by_region.csv). Track via LFS.
3. Implement a simple bar chart (D3 or your preferred lib) that reads the CSV.
4. Add a Python or Node script to validate columns and output a summary to dist/.
5. Configure CI to lint JSON, validate CSV headers, and run the build.
6. Create a feature branch to add a legend; open a PR with screenshots.
7. Resolve any conflicts that arise, merge, then tag v1.0.0 with release notes listing the data snapshot.
8. Update README with run/build steps and data provenance.

Practical project ideas

• Metric storybook: A repo that renders multiple key charts from sample datasets, with each chart as its own folder and testable build step.
• Data snapshot visual: Weekly tag with a new data snapshot and a changelog describing metric deltas; automate checks to flag schema changes.
• BI-export pipeline: Source-controlled scripts that export dashboards to static images or HTML, validated and tagged for each release.

Subskills

• Git Basics For Visualization Projects — Initialize repos, structure folders, commit cleanly, and set helpful .gitignore.
• Branching And Pull Requests — Use feature branches, push, review changes, and merge safely.
• Managing Assets And Data Files — Apply Git LFS for large files; keep small, canonical samples in-repo.
• Code Review Practices — Review for correctness, performance, accessibility, and visual integrity.
• Release And Tagging Basics — Tag versions and write release notes that capture data snapshots and build hashes.
• Handling Merge Conflicts — Resolve conflicts in JSON, CSS, and notebooks without losing intent.
• CI Basics For Builds And Checks — Automate linting, schema checks, and builds on push/PR.
• Documentation In Repo — Maintain README, contribution guide, and lightweight decision records.

Next steps

• Practice with the drills, then complete the mini project.
• Explore each subskill for focused learning and quick wins.
• Take the skill exam to check your readiness. Anyone can attempt it; logged-in learners get progress saved automatically.