Branching, contributing, and the files you must never commit
⏱ ~15 minutes
Each analyst owns one or more chapters. Without branches, two analysts editing the book at the same time would constantly collide. Branches give each contributor an isolated workspace — changes stay separate until they're reviewed and merged.
Think of it like working on your own copy of a shared document. You make your changes, then propose them for inclusion. The project lead reviews, approves, and merges.
Use the pattern yourname/chapter-or-feature:
Rules: lowercase, hyphens between words, include your name or initials. No spaces, no uppercase, no special characters.
Always branch from an up-to-date main to avoid carrying stale history.
git checkout main
git pull
git checkout -b yourname/chapter-nameEdit your chapter and scripts. When ready, render to update the freeze cache.
quarto render chapters/0X-topic/index.qmdCheck the four files appear as modified or untracked — and that nothing unexpected has changed.
git statusNever use git add .. Name every file individually.
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
# If you have new plots:
git add _freeze/chapters/0X-topic/index/figure-html/Use feat: for new indicators, fix: for corrections, docs: for narrative changes. First line under 50 characters.
git commit -m "feat: add apprenticeship starts indicator"Push your branch and create a PR on GitHub. Assign a reviewer.
git push -u origin yourname/chapter-nameIf these appear in git status, do not git add them:
| File | Why it must stay local |
|---|---|
renv.lock, renv/activate.R |
The shared R environment — only the project lead changes these. Your version may differ. |
weca_regional_indicators.Rproj |
IDE configuration file. Differs per machine. |
data/raw/* |
Gitignored. Raw data is too large and often sensitive. Should never appear. |
Personal files (simon.R, scratch.qmd) |
Keep these local. They will confuse other analysts. |
.env |
Contains database credentials. Blocked by pre-commit hook. |
Why not git add .?
git add . stages everything it finds — including renv.lock, your .Rproj, and any personal scratch files. Stage by name so you know exactly what's going in.
This project uses conventional commits. The format is:
type: short description (≤50 chars, imperative mood)
Optional body explaining why — not what.| Type | Use for |
|---|---|
feat: | A new indicator or chart |
fix: | Correcting a calculation, a broken render |
docs: | Narrative text only, no code changes |
chore: | Housekeeping — updating gitignore, CI config |
refactor: | Code restructured, no behaviour change |
Drag the steps into the correct order for a complete contribution. Then click Check order.
Click an answer — explanations reveal after each selection.
Heather is starting work on the transport chapter. Which branch name follows the project convention?
yourname/chapter-or-feature: lowercase, hyphens, name first. heather/transport matches exactly. Underscores, capitals, and long prefixes like feature/ are not used in this project.
You've staged your four files and are writing your commit message. You added a new GHG emissions indicator. Which message is correct?
feat: for a new indicator), imperative mood ("add", not "added"), and ≤50 characters on the first line. The third option is correct. "Update" is too vague; "WIP" should never be committed; bare sentences without a type prefix don't follow the convention.
After rendering, git status shows renv.lock as modified. What should you do?
renv.lock defines the shared R package environment for the whole team. Only the project lead should update it. If it appears modified locally, it means your R session diverged from the project's pinned versions. Do not stage it. Stage only your four named files.
Primary source: CONTRIBUTING.md — git workflow, branch conventions, PR template, and the peer review checklist.
Have a question? Ask your teacher in this conversation — just type it and continue the session.