Reproducible Research › Module 3: Version control
Commits that tell a story
Lesson 2 of 3 · 2 min
Your commit history is a diary of the project. Good messages make it useful; bad ones make it noise.
Bad and good
| Bad | Good |
|---|---|
| update | Drop participants who failed the attention check |
| fix | Fix off-by-one error in train/test split |
| stuff | Add figure 3: accuracy by dataset size |
| asdf | Switch optimiser to AdamW; lr 3e-4 from tuning run 12 |
- update
- Good: Drop participants who failed the attention check
- fix
- Good: Fix off-by-one error in train/test split
- stuff
- Good: Add figure 3: accuracy by dataset size
- asdf
- Good: Switch optimiser to AdamW; lr 3e-4 from tuning run 12
Rules for messages
- Say what and why, not how. The code shows how.
- Start with a verb in the present tense: Add, Fix, Remove, Update.
- Keep the first line short (around 50 characters). Add details on later lines if needed.
Rules for commits
- One idea per commit. Fixing a bug and adding a feature are two commits.
- Commit working states. Each commit should run, if possible.
- Commit before big changes, so you can always come back.
Why it matters for research
Six months later, when a reviewer asks why the numbers changed between drafts, git log shows you: "Drop participants who failed the attention check", on 12 March. That is your lab notebook, written automatically.
RememberOne idea per commit, a message that says what and why. Your history becomes your lab notebook.