nanalLabs BlogSearch "software research notebook" or "how to write an SW research notebook" and most results are pitches from services that connect to a GitHub repository and auto-collect commits, issues, and comments. That sounds convenient, but the question practitioners actually care about is what comes next — does that collected commit log actually satisfy what a government R&D project or a corporate research institute requires of a research notebook, or does it leave gaps that surface later in a spot check or a tax-credit follow-up audit? This post breaks down what Korea's national R&D research notebook guidelines require, item by item, against what a commit history does and doesn't cover.
The guidelines don't care about the medium — so why do software teams get confused?
Korea's national R&D research notebook guidelines (a notification from the Ministry of Science and ICT) define a research notebook as "material that records the process and outcomes of carrying out an R&D project," and recognize both paper and electronic-document formats. A 2021 revision relaxed the format requirements enough to bring in video, audio, and photo records, and leaves the specific requirements and methods up to each research institution's own internal regulations. That's exactly why the question "isn't the repository itself a recording medium?" comes up naturally.
The catch is that while the guidelines don't care about the medium, they do require certain properties regardless of medium: immediacy (chronological recording right after the work), preserved correction trails (the original has to remain visible even after a fix), and author/reviewer verification (who wrote it, who checked it). A commit history automatically satisfies some of these and structurally fails to satisfy others.
What a commit history covers, and what it doesn't
| Guideline requirement | Does a commit history cover it automatically? | Note |
|---|---|---|
| Immediacy (chronological, right after the work) | Partially | Commit timestamps run on the local system clock, which can be manipulated — they can differ from when the remote actually received the push |
| Author verification | Yes | Automatically identified via commit author/committer |
| Preserved correction trail | No — actively risky | force-push, rebase, and squash erase prior history. Without branch protection, this becomes "deletion without correction" |
| Purpose, method, and interpretation of an experiment | No | Commit messages like "fix bug" or "wip" carry no purpose or interpretation — that has to be filled in separately |
| Record of failed experiments | No | Deleting the commit for reverted work erases the failure from the log entirely |
| Reviewer verification | Partially | PR review/approval can map to this, but the institution's own regulations need to explicitly designate reviewers for it to count as "reviewer verification" |
The biggest trap is the correction trail. What the guidelines require for a correction is essentially "cross out the original with two lines and leave a signature and date, so the original stays visible" — and git's default workflow, especially the habit of rewriting history with force-push, does the exact opposite: it erases the original and overwrites it with new history. If a spot check or tax-credit follow-up audit asks "why did the record from this point in time disappear," and there's no answer, it can undermine the credibility of the entire commit history.
What it takes, at minimum, for a software repo to count as a research notebook
- **Protect the main/release branches against force-push and history
rewrites** (GitHub branch protection). When a correction is needed, add a new commit and record the reason in the commit message.
- Put the "what and why" in the commit message. Instead of "fix" or
"update," write at least one line summarizing the purpose of the experiment and the result — you need to be able to reconstruct the guideline's "experiment name/purpose" and "result and interpretation" fields from the commit log later.
- Write PR reviewer assignment into the team's own regulations, so
review approval has a documented basis for counting as "reviewer verification."
- Record failed experiments as revert commits with a stated reason —
don't delete the whole branch or erase them with force-push.
- Handle the repository's own retention separately. Secure a backup
that stays accessible for the retention period the project requires, in case the service account is terminated, the org transfers ownership, or the repo goes private — this is the same problem as what backing up an electronic research notebook actually requires.
- Record conditions outside the code separately — dataset versions,
hyperparameters, and the like. A commit records what changed, but not the external conditions (data source, runtime environment) needed to reproduce the experiment.
In the end, a commit history can be the skeleton of a software research notebook, but satisfying what the guidelines require — especially the correction trail and failure records — takes team-level workflow rules on top of it. Check your own institution's or project's research notebook regulations before applying any of this.