Software sustainability checklist from the Netherlands eScience Center

By Mateusz Kuzak, Netherlands eScience Center 

At the Netherlands eScience Center we aim to share as much code as possible between our diverse research projects. We also want to share our code with research communities. One of the reasons why we do this is to increase sustainability of our software, by extending its life beyond the life of our projects. 

How to practically approach this goal? What makes software easy or hard to take and reuse for your own project? What makes it easy to contribute to and to improve it?

 It's not enough to put open source license on our  software. We must minimize the friction of software reuse and contribution. This is why we recently designed a checklist for code developed at the eScience Center. It has been largely influenced by open source software community standards. Some of the decisions are arbitrary (like the choice of GitHub as code hosting service). We want the checklist to be easy to follow, without long discussions on implementation. We would be very keen to to get some feedback on it from research software developer community.

Version control

  • version control from the beginning of the project
  • use Git as VCS
  • use GitHub flow branching model
  • public VCS repository (GitHub)
  • meaningful commit messages

Release

  • semantic versioning
  • tagged releases
  • one command install (pip, npm etc)
  • using a package manager (pypi, npm etc)
  • quick-scan by other engineer (is the documentation understandable, can the software be easily installed, etc)
  • notify the communication person to help with dissemination (news item on site / annual report, etc)

Licensing

  • Apache 2 license
  • compatible license of all libraries
  • NOTICE(.txt|.md) listing licenses
  • request to cite the related paper, if applicable

Communication

  • project discussion list (GitHub issues or gitter) for all project related discussions from the beginning of the project
  • for services: a demo docker image in DockerHub (with Dockerfile)
  • for websites: an online demo
  • pitch presentation (1 to maximum of 3 slides)

Testing

  • unit tests
  • regression tests
  • build tests
  • continuous integration publicly available via Travis CI
  • continuous code coverage and code quality metrics public with minimum 70% coverage required
  • end2end test for (web) user interfaces

Documentation

  • README.md - clear explanation of the goal of the project with pointers to other documentation resources
  • well defined functionality
  • source code documentation
  • usage documentation
  • documented development setup (a good example is Getting started with khmer development)
  • contribution guidelines
  • documented code style

Development setup

  • using the NLeSC coding style is required
  • editorconfig
  • applied code style in automated way if possible (i.e using linters and code formaters)
  • dev environment docker images in Dockerhub (with Dockerfile)

Use standards

  • exchange format (Unicode, W3C, OGN, NetCDF, etc)
  • protocols (HTTP, TCP, TLS, etc)
Posted by a.pawlik on 26 November 2015 - 7:35pm

Add new comment

The content of this field is kept private and will not be shown publicly.
By submitting this form, you accept the Mollom privacy policy.