WECA Workflow — Quick Reference

How the freeze cache works

Source fingerprint == html.json fingerprint? ✅ MATCH → use cached outputs. Done. ❌ MISMATCH → try to re-run code → FAIL (no raw data on GitHub)

Any edit to your chapter shifts its hash. Always re-render and commit the updated html.json after editing.

The four files — always together

File	Location
Chapter source	`chapters/0X-topic/index.qmd`
Indicator script	`scripts/R/0X-topic/RI_XY_name.R`
Fact CSV	`data/fact/RI_XY_name.csv`
Freeze snapshot	`_freeze/chapters/0X-topic/index/execute-results/html.json`

Contribution workflow

Checkout main, pull, create branch
git checkout -b yourname/chapter-name
Edit chapter, render locally
quarto render chapters/0X-topic/index.qmd
Check git status before staging anything
git status
Stage the four files by name — never git add .
Commit with conventional message
git commit -m "feat: description"
Push & open PR on GitHub

Branch naming

Pattern: yourname/chapter-or-feature

heather/transport alex/environment megan/04-skills Transport Chapter feature/new_stuff MyBranch

Lowercase, hyphens, include your name. No spaces, no capitals, no underscores.

Commit message types

Prefix	Use when
`feat:`	New indicator or chart
`fix:`	Correcting a calculation or broken render
`docs:`	Narrative text only, no code changes
`chore:`	Housekeeping (gitignore, CI config)
`refactor:`	Code restructured, no behaviour change

First line ≤ 50 chars, imperative mood: "add", not "added".

Never commit these

File	Reason
`renv.lock`	Project lead only
`*.Rproj`	IDE config, per-machine
`data/raw/*`	Gitignored, too large
`.env`	DB credentials — blocked by hook
Personal scratch files	Keep local

Error index — cause & fix

Error: `path` does not exist: '.../data/raw/...' Cause: source edited, freeze cache not re-committed.
Fix: re-render, git add updated html.json, commit & push.

error: failed to push some refs … Updates were rejected Cause: remote has commits you don't have locally.
Fix: git pull origin branch-name then push again.

no changes added to commit Cause: forgot git add before git commit.
Fix: git status, then git add the right files.

Error in source(...): cannot open file 'scripts/R/...' Cause: R script exists locally but was never committed.
Fix: git add scripts/R/… + data/fact/…, commit & push.

Committed/pushed to wrong branch Cause: forgot to create or switch to feature branch.
Fix: git branch yourname/chapter from current HEAD, git reset --soft HEAD~1 on wrong branch, re-commit on correct branch.

Quick command reference

# Start a contribution
git checkout main
git pull
git checkout -b yourname/chapter-name

# Render
quarto render chapters/0X-topic/index.qmd

# Stage (name every file)
git add chapters/0X-topic/index.qmd
git add scripts/R/0X-topic/RI_XY_name.R
git add data/fact/RI_XY_name.csv
git add _freeze/chapters/0X-topic/index/execute-results/html.json

# Commit
git commit -m "feat: add X indicator"

# Push and open PR
git push -u origin yourname/chapter-name

# Force re-render (data updated, source unchanged)
quarto render chapters/0X-topic/index.qmd --execute-freeze refresh

# Check what will re-execute
quarto render --dry-run

WECA Regional Indicators — Workflow Quick Reference