A simple checklist to make code accompanying research papers fairly FAIR: findable, accessible, interoperable, and reusable. This guide is for researchers that want to make code available online with minimal effort. These steps are accessible to everyone, and ensure you are following (almost) all FAIR principles with minimal effort.
1. Create a GitHub account
You'll only need to do this once! Using a platform where you can host your code repository publicly allows others to browse, use, and (optionally) contribute to your code. We recommend Github because of its easy integration with Zenodo (which we use later), but you could also consider alternatives like Gitlab or Codeberg.
The intent is to share your code with everyone to allow them, so don't overthink it! You can also find more in-depth information in the Turing Way book.
3. Create a code repository on Github and upload your code
When creating a repository, make sure to select the license you choose in step 2 in the "Choose a license" dropdown menu. Be mindful not to upload code or data that may contain privacy sensitive elements.
4. Write a README
In your README, include at least the following information:
- Overview: What is the purpose of your code?
- Prequisites: What other software or hardware is required to run your code?
- Usage: How can users run your code? Are there parameters to your code?
- License: Under which license did you make your code available?
- Citation information: How should others cite your code? (you do this in step 9)
- Contact: Who should be contacted with questions or reports about your code, and how?
We want to ensure that there is a persistent way to refer to exact versions of your code. Repositories such as Zenodo issue Digital Object Identifiers (DOI). There are alternatives, but we recommend Zenodo because of its GitHub integration.
By linking the repository, you can make sure a persistent DOI is assigned to each release. This important so that others can refer to specific versions of your code.
A release signifies an easily recognizable and specific iteration of your code, and will trigger Zenodo to create a DOI.
In Zenodo, add all relevant metadata by going to the record page and clicking the orange Edit button in the top-right corner.
You will be taken to a form where you can edit the metadata.
Once you are done modifying it, click Save and then Publish.
Good metadata can help people find your code, and provides them context.
On the right panel in Zenodo under Details, click on the badge with the doi, and copy the markdown text into the top of your README file. The DOI badge is a sign that your software will remain findable. Then, add a “Citation” section to the bottom of your README, and copy the citation info from Zenodo into it.
Now you can add the DOI to your code availability statement in the manuscript according to the venue's guidelines. This ensures that everyone that reads your paper will also have access to your code.
First, congratulations on publishing Fairly Fair Code! The steps you took greatly improve the ability for other people to understand and use your work, and will be appreciated by many future readers (possibly even your future self :)). For completely FAIR code, it is also important that:
- The code uses no proprietary dependencies, data, or data formats. Consider using an open data format.
- The code and documentation follow domain-relevant community standards. You may consider standards from your scientific domain as well as standards for default project structures.
Your project may already adhere to that, and if so, great! If not, you may either go back and revise it, or simply keep it in mind for the next project you do. If you're interested in taking it even further, the Turing Way is a great digital resource for all things reproducible, ethical, and collaborative (data) science.
This is not meant for software packages, libraries, or workflows, where stricter standards should be employed! This is only one of many ways to make your code FAIR. We chose this workflow for its simplicity.
This document is inspired by the FAIR Cheatsheets of Utrecht University.
This document was written during the 2024 Open Science Retreat by Niklas Hohmann, Ana Martinovici, Christian Meesters, Benedikt Langenberg, Kjong Lehmann, and Pieter Gijsbers (in no particular order). We also thank other attendees of the event for their thoughtful input and suggestions.