FAIR checklist for research software

This checklist provides a set of recommendations for FAIR software. It outlines best practices and guidelines to ensure the quality, reproducibility, and sustainability of software projects. The checklist covers various aspects, such as version control, documentation, testing, licensing, and collaboration, providing a comprehensive framework for improving your software development process.

Checklist

Version control

Essential

• Use git as a version control system
• Upload your project on GitHub or TU Delft GitLab

Recommended

• Make your repository public
• Consider your branch hygiene
• Use a branching model (e.g. GitFlow)
• Use meaningful commit messages

Collaboration

Essential

• Make use of GitHub issues

Recommended

• Contribution guidelines
• Code of conduct

Project documentation

Essential

• README
• Apply a TU Delft pre-approved LICENSE
• CITATION

Software documentation

Essential

• Source code documentation (docstrings)
• Document your project dependencies
• Installation instructions
• User documentation

Recommended

• Developer documentation and setup
• Examples and tutorials (e.g. Jupyter Notebooks)

Optional

• Documentation tools (Sphinx, JupyterBook, Quarto)
• Build an API reference from docstrings
• Hosting (GitHub Pages, Readthedocs)

Software testing

Essential

• Installation/execution verification

Recommended

• Defensive programming
• Test your software with integration tests and unit tests
• Make use of Continuous Integration to automate testing

Optional

• Code coverage check (e.g. Sonarcloud, codecov)

Software quality

Essential

• Organize your project for reproducibility
• Record and manage your software dependencies

Recommended

• Make refactoring part of your workflow
• Follow best coding practices

Recommended for Python

• Follow PEP8 guidelines
• Use a tool for dependency management (e.g. poetry)
• Use linter (e.g. pylint, flake8)
• Use a formatter (e.g. black)

Releases

Essential

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

Recommended

• Use semantic versioning
• Create tagged releases (GitHub)
• CHANGELOG
• Upload to registry (e.g. PyPI, conda)
• Releasing guide

Optional

• Continuous Integration for automated build and release

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.

For more information on the principles behind FAIR software, please have a look at the following resources:

• The Turing Way - Guide for Reproducible Research - general guide to reproducible research
• Towards FAIR principles for research software - publication on the translation of FAIR principles for data to FAIR principles for software
• From FAIR research data toward FAIR and open research software
• FAIR Principles for Research Software

Acknowledgements

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