Version control and code review for research software
Use this skill when helping someone put research code under version control,
shape a collaboration workflow, or review code (their own or a teammate's).
The aim is software whose history is traceable, whose changes are reviewed
before they land, and whose results others can reproduce. Version control and review are
two halves of one loop: commits and branches create reviewable units, and
review is what keeps what lands on the main branch trustworthy.
Choose a version control system
Default to git for almost every research project unless a concrete
constraint says otherwise:
- Git is the community's standard and the right choice for research
projects: collaboration, review and archiving tooling all assume it
(the strongest-current-tool rule applies to version control too).
- Large binary files (datasets, models, images) do not belong in plain
git history: use a data versioning layer (DVC, git-annex, DataLad -
rseng-data-management) or git-lfs for media-style assets.
- A team new to version control still starts with git - budget training
time (rseng-trainer) rather than reaching for a gentler-seeming legacy
system; inherited repositories in older systems (SVN, Mercurial) are
a migration task, not a reason to stay.
Set up the workflow, not just the repo
Choosing a tool is the easy part; the value comes from an agreed workflow:
- Define a branching strategy up front. Keep the main branch releasable;
do work on short-lived feature branches and merge back via review. Adopt
a heavier model such as Git Flow only when project size warrants it - do
not impose ceremony a small team will not follow.
- Set commit conventions. Write small, focused commits with clear messages
that say why a change was made, not just what. One logical change per
commit keeps history bisectable and reviews small.
- Integrate with the development environment. Wire the VCS into the IDE or
editor (VS Code, RStudio, PyCharm, Eclipse) so committing and diffing are
part of normal work, and connect continuous integration so tests run on
every push.
- Make reproducibility explicit. Tag the exact versions used in
publications, and keep configuration files and dependency
specifications in version control alongside the code.
- Collaborate through a platform. Use GitHub or GitLab for sharing, issues,
and pull/merge requests; make review a standing part of merging.
- Maintain the repository. Back it up, prune stale branches periodically,
and review access permissions.
Commit-message checklist: imperative summary line under ~50 characters; a
body that explains motivation and any trade-offs; reference the issue or
ticket it addresses; avoid dumping unrelated changes into one commit.
Authorship and signatures live in commit metadata
Who wrote a change, who committed it, and whether it is verified are
facts git records in dedicated, machine-readable places. Keep them
there - not in file headers, not in commit-message prose:
- Identity is configuration. Set
user.name and user.email correctly
per project (institutional vs personal identity) BEFORE the first
commit; forges, citation harvesters and contributor counts all read
these fields. Use git commit --author when committing a change
someone else wrote - git separates author (wrote it) from committer
(recorded it) for exactly this case.
- Multiple authors are trailers. Record co-authors with
Co-authored-by: Name <email> trailers - the standard,
forge-recognized mechanism - rather than naming people in the message
body or a file header.
- Signatures are commit signatures. Verification means signed commits
and signed tags (
commit.gpgsign, gpg.format ssh for SSH signing
keys, git tag -s for releases), checked with
git log --show-signature or the %G? format field. Sign at least
the release tags that publications cite - a signed tag anchors
provenance (rseng-provenance) far better than any statement in a
README.
- Fix identities with .mailmap. When names or emails vary across
history, normalize them with a
.mailmap file - the metadata-native
correction - and NEVER rewrite published history to edit authors or
signatures; corrections go forward.
- Do not duplicate metadata into files. "Author: X, modified by Y on
<date>" headers in source files rot immediately and contradict the
history;
git log and git blame are the record (license/SPDX
headers are a different thing and are fine). Likewise keep commit
messages about the WHY of the change - the who/when/verified facts
already live in the metadata fields.
- Keep it truthful. The author field, trailers and signatures must
reflect who actually did the work - including agent contributions
where project policy records them; misrepresenting authorship in
metadata is a concealment request (rseng-honesty), and accurate
metadata is what contributor credit is harvested from
(rseng-citation-metadata).
Run code review as a first-class practice
(Scope note: this skill covers PR-time review process and rules;
retrospective codebase audits and milestone project reviews are
rseng-code-review, and diff-time pre-review craft is
rseng-pair-programming.)
Code review is systematic examination of code - a teammate's, or your own
after time away - to find bugs, raise quality, and enforce shared standards. It pays off: rigorous inspection can remove 60-90% of
errors before the first test run, and fixing a defect early costs 10-100x
less than fixing it later. Beyond defect-catching, review spreads knowledge
across the team, improves reusability and reproducibility, and helps onboard
new members.
Structure every review through a pull/merge request so discussion, diffs,
and suggestions stay attached to the change.
What to look for
Focus the review on substance:
- Correctness - does the code do what it is supposed to, including edge
cases?
- Style and consistency - are naming, formatting, and structure consistent
with the project's agreed conventions?
- Testing - are there tests, and do they cover expected and edge-case
behaviour?
- Documentation - are functions, classes, and scripts clearly documented?
- Modularity - is the code split into reusable, testable components?
- Performance - is it efficient enough for the task (without premature
optimisation)?
What not to do
Reviews go wrong by overstepping as much as by missing bugs. Avoid these:
- Bikeshedding personal style. Do not argue single vs double quotes or
similar when the team has no agreed standard - let linters and formatters
settle it.
- Demanding rewrites. Do not push to rewrite large sections without a clear
reason such as a real bug or design flaw. Improve, do not take over.
- Blaming the author. Critique the code, never the coder; keep feedback
constructive and kind.
- Requiring perfection before merge. Functional, tested, clear code can
merge; minor polish can follow.
- Mislabelling severity. Mark minor or subjective points as non-blocking;
do not hold up progress for optional tweaks.
- Expecting mastery of everything. Researchers who code come from varied
backgrounds - do not expect deep software-engineering knowledge from
every domain expert.
Make review efficient
- Keep changes small. Small pull requests get faster, deeper review than
large ones - another reason for focused commits and short-lived branches.
- Automate the mechanical checks. Run linters and formatters (flake8,
eslint, Pylint) and a CI pipeline before human review, so reviewers spend
attention on logic and design rather than whitespace.
- Keep feedback constructive. Ask questions rather than issue verdicts;
reviewers learn as much as authors.
- Combine human and automated review. Automated tools catch style and known
mistake patterns; a human is still required for correctness, design, and
intent - neither replaces the other.
- For code underlying a paper, consider a CODECHECK-style independent
reproduction of the results as a heavier form of review.
Reviewer checklist to paste into a PR: correctness and edge cases checked;
tests present and meaningful; documentation adequate; naming and structure
consistent; no obvious performance traps; linter and CI green; comments
labelled blocking vs non-blocking.
How version control and review reinforce each other
- Branch per change so each unit of work is independently reviewable.
- Require review (a PR/MR approval) before merging into the main branch.
- Let CI gate the merge: tests and linters must pass before a human signs
off, so review time goes to judgement, not mechanics.
- Tag reviewed, released states so the reproducible version is
unambiguous.
Repository hygiene: no generated or binary artifacts
Keep compiled and generated files out of version control: build
outputs, packaged artifacts, rendered documents, caches and editor
droppings. They bloat history permanently, make diffs meaningless
and drift out of sync with their sources - a repository free of
binary artifacts is an explicit quality indicator. Add ignore rules
before the first build runs; large or binary DATA has its own
disciplined path (data versioning tools rather than git), and
deliberately committed result records (golden files, executed
notebooks) are fine when the policy says so explicitly - the rule is
"nothing generated without a stated reason", not zealotry.
Working with this skill
The generated references.md beside this file lists the source
material and pointers:
- references.md - verified Learn more pointers
Learn more (verified):
<!-- related-skills:begin -->
Related skills
Check whether any of these applies before moving on:
- rseng-ci-cd - CI gating merges before human review
- rseng-citation-metadata - commit metadata feeds contributor credit
- rseng-contributor-onboarding - review as an onboarding channel
- rseng-data-management - DVC/git-annex for large data files
- rseng-notebooks - jupytext twins make notebook diffs reviewable
- rseng-publishing-releasing - tags marking published versions
- rseng-software-peer-review - CODECHECK-style heavier review of paper code
<!-- related-skills:end -->