Tools for Digital Theory Objects

Making Theories FAIR by Version control, CFF citation files & Semantic Versioning

Felix Schönbrodt

felix.schoenbrodt@psy.lmu.de

Ludwig-Maximilians-Universität München

Aaron Peikert

peikert@mpib-berlin.mpg.de

Max Planck Institute for Human Development

2025-10-17

Git Showcase

Git overview

Git is a tool from software development that solves two major challenges:

Tracking changes in source code (or any text files)
- Keeps a complete version history and allows reverting to previous states.
- Enables reproducibility by “freezing” project states (releases, tags).
How to work collaboratively on the same files.

Git overview

Git hands-on

Showcase how git works
- Lecturer creates a private project on Github for this course. This will be the central project for submitting homework.
- Students create their Github accounts; add them as contributors to the course project.
- Show how to commit, push, pull changes.
- Show a merge conflict (make a change in the web frontend and locally) and how to resolve it.
We start the OSC git tutorial together to weed out technical hurdles. Aim to get until section “Secure the connection between your computer and GitHub”. The rest of tutorial is homework until next week.
- Note: In chapter “Secure the connection …” it says “You will then be asked to provide a passphrase. Protecting your keys with a password is optional but highly recommended”. I recommend not to set a passphrase (just leave it empty), unless you deal with very sensitive data. You will get crazy if you need to enter your passphrase at every SSH operation.

Never forget …

CFF citation files

Citation File Format schema version 1.2.0

Tell other users how your theory should be cited, what the current version is, and more meta-data. This can be stored in a file called CITATION.cff in the top level folder of your repository:

cff-version: 1.2.0
title: 'AST: Action selection theory'
message: >-
  If you refer to this theory, please cite it using the
  metadata from this file. This theory has not been peer reviewed yet.
type: report
authors:
  - given-names: Felix
    family-names: Schönbrodt
    email: felix.schoenbrodt@psy.lmu.de
    orcid: 'https://orcid.org/0000-0002-8282-3910'
    affiliation: Ludwig-Maximilians-Universität München
repository-code: 'https://github.com/nicebread/AST'
abstract: >-
  A theoretical model that explains how a donkey solves the
  approach-approach conflict of hunger and thirst when the
  two sources are separated.
keywords:
  - approach-approach conflict
  - action selection
  - motivation
license: CC-BY-4.0
version: 0.2.5
date-released: '2023-10-30'

Citation File Format schema version 1.2.0

How to create

Create an initial version of your CITATION.cff file with the cffinit tool

Citation File Format schema version 1.2.0

How to create

The tool currently only knows “software” and “data set” as types. Create it with type software and update the message field:

message: >-
  If you refer to this theory, please cite it using the metadata from this file.
type: software

Save the CITATION.cff file in the top level folder of your repository.

Effect of a CITATION.cff file

Both Github and Zenodo (and probably more repositories) parse an existing CITATION.cff and display the citation information:

Citation File Format schema version 1.2.0

Peer review status

For users of your theory, it is helpful if the peer review status is made explicit.
This can be done in the message field, e.g.:
- “This theory has not been peer-reviewed yet.”
- If the current version is, say, 2.1.0: “The last peer-reviewed version was 1.0.4”
- “An open peer review of version 1.0.2 is published at doi …”
In future versions of the cff schema, one could also use the isReviewedBy annotation of an identifier.

Folder Structure

Recommended folder structure for our formalization projects

.
├── README.md (this should link to any associated Google docs, if applicable)
├── CITATION.cff
├── VAST_display.drawio
├── simulation/
│   ├── README.md
│   ├── raw_data/ (a subfolder with empirical raw data, if applicable)
│   │   └── dat.csv
│   ├── functions.R (or any other name)
│   └── ...
└── manuscript/
    ├── manuscript.qmd  
    └── ...

Semantic Versioning

Semantic Versioning (semver)

Version numbers have three numbers: MAJOR.MINOR.PATCH.

Increment the:

MAJOR version when you make changes that break backward compability
MINOR version when you add functionality in a backward compatible manner
PATCH version when you make backward compatible bug fixes

The numbers are plain integers! For example, after 9 comes 10:

0.9.0 → 0.10.0 → 0.11.0 → 1.0.0 → 1.1.0

Some rules & conventions:

The first development version starts with 0.1.0
The first stable public release is 1.0.0
Once a versioned package has been released, the contents of that version must not be modified. Any modifications must be released as a new version.
Major version X (X.y.z) must be incremented if any backward incompatible changes are introduced. Patch and minor versions must be reset to 0 when the major version is incremented.

Example

First commit to repository: 0.1.0
Oh, I found and corrected a typo: 0.1.1
Implemented a minor new feature (that does not break the functionality of the existing features): 0.2.0
- Always reset the patch number to zero when increasing the minor or major number
By and by, more features get implemented: 0.3.0 → 0.4.0 → ... → 0.12.6
Now we are ready to tag our first public release! 0.12.6 → 1.0.0
…
After years of work and minor version updates (e.g., 1.4.0), we made a huge change that makes the product incompatible to version 1: 2.0.0

Patch, Minor, Major changes

So what changes warrant what kind of version increments? For theories it makes sense to think in terms of predictions.

patch: The predictions your theory makes do not change, instead you have clarified things, defined terminology, fixed typos, added references etc.
minor: The predictions your theory makes have expanded but previous predictions are substantively compatible, i.e. the theory makes the same prediction as older versions for the same settings. All things that would have confirmed or falsified the older version, still apply to the new version. For example, you have included more settings your theory covers; added more previously unrecognized variables; became more certain about some predictions (i.e. range predictions became narrower); added more operationalizations for constructs.
major: Evidence that would have confirmed or falsified the previous version does differently affect this version. You changed core tenets of the definition of constructs or their operationalization, changed the functional relationship between two variables, changed the type of a relation (causation to correlation) or the timescale of a process, etc.

Git best practice

The version number is recorded in two places:

In the CITATION.cff file
In the names of all tags or releases

Is every commit a new version? That would be very tedious, especially if you are currently developing the theory and have frequent commits. We recommend:

Maintain a dev developer branch for ongoing development. It is not necessary to update the version number in each development step.
Whenever a stable stage has been reached:
- Increase the version number in the CITATION.cff file
- Record the substantive changes in your CHANGELOG.md
- Push the development branch to the main branch
- Create a tag or release on the main branch and write the version number into the label of the tag (see also “How to create a release?”)

What is a “release” on Github?

Create a tag or a release whenever a major or minor version is released:

With tags and releases, you can “pin” and label important commits in your history.
Users can quickly go to a specific “frozen” version of your repository.
These releases can be expected to be stable/functional versions of your software or theory (but see also semantic versioning: Everything with a 0.x.x version probably is not properly tested yet).
In our context, there is no real difference between tags and releases, you can use either.

Git best practice

(of course more complicated setups with multiple branches, e.g. feature branches, are possible).

How to create a release?

Use GitHub’s inbuild release mechanism
Remember to set the tag to the correct version number
Copy the content of your CHANGELOG.md into the release notes.
Optional: create a DOI for your release, and archive it with Zenodo
Optional: update your CITATION.cff file to include the new DOI
- This is a hen/egg problem: The doi will not be in the release itself, as it is assigned only after the release.

End

Contact