FAIR software checklist

To ensure your research software is findable and usable by other researchers, we have compiled a checklist to improve its FAIRness (Findable, Accessible, Interoperable, Reusable).

Checklist

The checklist below is in part based on the checklist provided by the eScience Center, licensed under CC BY 4.0.

Version Control

Essential

• Use git as a version control system

• Upload your project on GitHub or TU Delft GitLab

Recommended

• Make your repository public

• Branch hygiene

• Use a branching model (GitFlow)

• Meaningful commit messages

Documentation - Repository

Essential

• README

• LICENSE

• CITATION

Recommended

• Make use of Github issues

• Contribution guidelines

• Code of conduct

Documentation - Software

Essential

• Source code documentation (docstrings)

• Installation instructions

• Usage documentation

• Developer setup

Recommended

• Examples and tutorials (Jupyter notebooks, videos, screencasts)

• Website (github.io pages, Readthedocs, JupyterBook

• Build API reference from docstrings

Testing

Recommended

• Defensive programming

• Test your software with integration tests and unit tests

• User installation test

• Make use of Continuous Integration

• Code coverage check (Codecov, Sonarcloud, Travis)

Releases

Essential

• Obtain a DOI (Zenodo or 4TU.ResearchData)

Recommended

• Semantic versioning

• Tagged releases (GitHub)

• CHANGELOG

• Upload to registry (PyPI, conda, DockerHub)

• Release guide

• Continuous Integration for build and release

Code quality

Essential

• Project organisation

• Record software dependencies

Recommended

• Follow PEP8 guidelines

• Use linter (e.g. pylint, flake8)

• Use a formatter (e.g. black, yapf)

• Follow best coding practices

Example repositories

• eScience Center - matchms - Matchms is an open-source Python package to import, process, clean, and compare mass spectrometry data.

• TU Delft - Transposonmapper - Transposonmapper is an open-source python package and Docker image for mapping transposons from sequencing data.

References

For a full overview of the principles behind FAIR software, please have a look at the following resources:

• FAIR software checklist - five recommendations for FAIR (scientific) software

• Towards FAIR principles for research software - publication on the translation of FAIR principles for data to FAIR principles for software.

• Guide for Reproducible Research - general guide to reproducible research

• The Zen of Scientific Computing - Scientific computing tips from Aalto University

• From FAIR research data toward FAIR and open research software