“To plant a garden is to believe in tomorrow” - Audrey Hepburn
What happens when we don’t tend to a garden?
Plants are denied water, sunlight and vital nutrients; weeds are left to flourish and grow, suppressing the preferred cultivars; plants that don’t reach fruition are refused the opportunity to return in subsequent years. When we don’t tend to a garden, it loses its ability to be a sustainable resource.
What happens when we don't tend to software?
The same thing can happen to software if it is not maintained, argued Dave Bunten, software engineer at the Department of Biomedical Informatics (DBMI) at the University of Colorado Anschutz.
Much like a garden, software requires careful tending and maintenance to ensure it is fruitful for years to come. Bunten developed the Software Gardening Almanack to help software researchers tend and maintain their software gardens. “Software isn’t a one-time product—it changes and goes through lifecycles which can be observed like a garden,” said Bunten. “Software is also complex; it’s difficult to know and implement all the best practices, even as an expert. The Almanack helps software become more sustainable by distilling these best practices for researchers.”
This is the second installment in our ongoing series spotlighting the DBMI Wall of Software, an interactive online hub showcasing the latest open-source software and data tools for researchers.
The Almanack is both an open-source handbook and a Python toolkit for building sustainable, maintainable and resilient software. Researchers can leverage the handbook to understand how they can practice sustainable software development, and they can utilize the Python package on software repositories to get near-instant suggestions on how they can improve the software.
“When we write a paper, we can use spellcheck or Grammarly to help highlight places where we can improve writing and correct things on the fly,” said Bunten. “We need things like this for research software development, too. In research software, there are all sorts of practices, tips and tricks that we employ, but it’s hard to keep all those things in our heads. We created the Software Gardening Almanack to help researchers to address these best practices on the fly and give the context necessary to understand them.”
One example of a ‘best practice’ that the Almanack emphasizes is the proper use of a referenceable DOI (digital object identifier). Often times, scientific writing will lack a reference to the specific version of a piece of software used. The Almanack can check whether this DOI is missing from the software and report this to the user. When these DOIs are present, they can then be used to relate the exact version of the software which was used as part of the research, which makes it replicable by other researchers.
The Almanack also checks for common documentation associated with high quality software. For example, the Almanack has specific checks for CODE_OF_CONDUCT files which help illustrate the expectations and repercussions of behaviors associated with the project. It also checks for CONTRIBUTING files, which help communicate how issues are raised, changes are created and the community is maintained long-term. Checks like these help scientific software developers recall that their software is about more than developing and maintaining the code—it’s about supporting the people surrounding the project, too.
The Almanack is meant to be implemented into the development process to support best practices. One way researchers can leverage the Almanack is through the `almanack check` feature (available from the Python package as a command-line interface tool). This feature allows researchers to quickly check their own repositories (or other researchers’ repositories) to better understand how the software aligns with the best practices suggested by the Almanack.
In the same way that gardeners rely on almanacks to guide planting and care throughout the seasons, researchers can now rely on the Software Gardening Almanack to cultivate and nurture their software—ensuring software can grow, thrive and bear fruits for years to come.
