FAIR Software Development

In the context of Open Science, software and code created in research projects are considered research outputs. Maastricht University’s Open Science Policy encourages researchers to apply the FAIR principles to software and code. The Research Data Management and Research Computing Support teams provide support for developing and managing research software and code in line with these principles.

Consider research software management from the onset of your project

Research Software Management is the process of organizing, maintaining and documenting software or code developed during a research project. It includes planning its development, use and maintenance, ensuring appropriate licensing, and making software accessible and reusable.

Planning how you will manage your research software from the start can help you:

  • Improve reproducibility by keeping track of code, dependencies and computational environments.
  • Prevent loss by storing code in an appropriate location.
  • Save time and computational resources by avoiding unnecessary reruns and making your code reusable by others.
  • Support collaboration and reuse by making code easier to understand and work with.
  • Meet requirements of funders and publishers and align with UM’s Open Science policy.

Research software management is commonly planned in a Software Management plan (SMP). An SMP is a brief roadmap for how code or software will be developed and maintained during a research project.

Resources

Use version control to manage your code

Computing infrastructures are designed to run computational workloads. Code stored on these infrastructures can be altered or deleted, and its immutability cannot be guaranteed.

As recommended in the Research Data Management Code of Conduct, use an appropriate institutional version control platform to host your code and manage its versions.

At Maastricht University, Git is the most used version control system. Git is a version control system that tracks changes to code over time, allowing you to collaborate, review changes and return to earlier versions.

GitLab and GitHub are platforms for hosting Git repositories and collaborating on code. Maastricht University provides an institutional GitLab environment, and several departments have GitHub accounts. Use the guidance on version control to explore the version control options available at Maastricht University. If you are unsure where to host, contact the research software steward.

How to use Git

Good practices in Git

  • Give your repository a comprehensive name: Choose a descriptive name that clearly reflects your research project or the software/code it contains. Follow naming conventions used by your department or research group where possible.
  • Commit frequently: Commit changes regularly, especially when modifying code or job scripts. Push working versions to a remote repository.
  • Make atomic commits: Keep commits small and focused on one logical change, making it easier to reproduce or revert changes.
  • Write descriptive commit messages: Clearly describe changes to code, job scripts, configuration, or computational workflows. Follow existing conventions or agree on a consistent format within your team where possible.
  • Do not commit sensitive information: Never commit passwords, tokens, personal data, or other sensitive information.
  • Do not commit all files: Computational workloads can generate a lot of output that can quickly increase the size of your repository. Avoid committing large or frequently changing binary files (e.g. images or videos), as they can make your repository large and slow. Exclude files that do not need to be tracked.
  • Version your software: Use a versioning scheme such as Semantic Versioning or Calendar Versioning common to your discipline.
  • Maintain a changelog: Document important changes between software versions.
  • Release stable versions: Create releases for stable versions of your code and use an appropriate repository/archive, such as GitHub-Zenodo synchronization, to assign a DOI.

Resources

Make your computational environment reproducible

A computational environment is the system in which your code runs. It includes hardware (e.g. number of CPU cores and GPUs) and software components (e.g. operating system, programming languages, libraries, its versions and configurations).

Your code and its output depend on this environment. If the environment changes, your code may produce different results or stop working. A reproducible environment helps you reproduce results later, move workflows between computational environments, and enable others to reuse your code.

Good practices for setting up a reproducible environment

  • Keep track of your setup: capture setup steps in scripts and track changes using Git.
  • Keep track of your dependencies: add documentation on your dependencies and their versions to your repository (e.g., requirement.txt file for Python code).
  • Use containers: Tools such as Docker package software and their dependencies into a reproducible environment. Containers create a virtual machine mapping the environment that your code or software needs to run.
  • Use SURF Research Cloud: Research Cloud allows you to easily set up virtual research environments using preconfigured or custom workspaces, datasets and cloud resources.

Resources