Figure 1. Following guidelines and practices outlined in an Almanack enhances software development, much like it nurtures growth in a garden.

Scientific software is at the heart of modern discovery, powering advancements across many fields.^1,2,3,4 Yet, beneath the surface of these achievements lies a sobering reality: much of scientific software is fragile due to low quality implementation or design⁵, which leads to challenges related to software collapse.⁶ These challenges jeopardize software sustainability, productivity, and trustworthiness, posing threats to the very foundations of research.¹ The Software Gardening Almanack⁷ offers a new way forward: treating software as an emergent, living ecosystem (Figure 1). The Almanack describes and implements Software Gardening principles that help to cultivate sustainable, reproducible, and high-quality scientific software.

Proliferation of fragile software ecosystems

The Consortium for Information & Software Quality (CISQ) estimated, in 2022 alone, that poor software quality cost the global economy a staggering $2.41 trillion.⁵ Scientific software is no exception. In many fields, it is the norm for scientists to publish articles that contain unusable, low-quality software and other analysis code. For example, the code might lack installation instructions, omit reproducible examples, or exclude critical documentation to understand the work.² These observations paint a clear picture of 1) significant training gaps for research software engineering⁸, 2) misaligned incentives for delivering reproducible software, 3) the difficulty evaluating software quality, and 4) codebases growing brittle with age.⁶ Despite these challenges, scientific software has experienced tremendous growth. For example, about 1.5 million repositories on GitHub that were created in 2024 contained at least one Jupyter notebook, showing 170% growth since 2022.⁹

But not all software decays so quickly, and some software can last decades. What measurements indicate whether a software repository will resist the challenges associated with poor quality and decay? GitHub Stars are often used to infer quality, but they may be fake and they may only demonstrate popularity as opposed to sustainability.¹⁰ Furthermore, publication and citation metrics indicate usage, but they suffer from diminishing returns due to increases in the overall number of citations in recent years, larger author or reference lists, and proliferation of self-citations.¹¹ While easy to see and measure, these metrics paint an incomplete picture. Instead, embracing software as a complex and evolving ecosystem enables us to quantify sustainability with many measurements and perspectives.

Tending software gardens

Figure 2. All software faces lifecycles that can be better understood through a Software Gardening lens to guide sustainable development.

We wrote about Software Gardening in an earlier blog post.¹² In that post, we compared Software Gardening to the more traditional metaphor of scientific software development as “software carpentry”.¹³ In software carpentry, software is viewed as a craft that emphasizes precision, reproducibility, and start-to-finish construction. However, this analogy falls short of addressing the multidimensional challenges of time. Software decays, requirements evolve, and development grows through collaborative teams. Software Gardening¹² offers a new, complementary lens for rethinking software development. While carpentry emphasizes the skills and tools to build software, the lessons are static and product focused. Instead, Software Gardening is about nurturing growth, adapting to changes, and preparing for inevitable elements of decay (Figure 2). A software gardener tends to their "code ecosystem" much like a gardener cultivates a garden. A software gardener removes weeds, enriches the soil, and ensures that the environment where software development happens supports healthy, sustainable growth.

Introducing the Software Gardening Almanack

Figure 3. The Software Gardening Almanack is an open-source digital book and open-source Python package. The Python package includes both reporting and linting functionality.

The Software Gardening Almanack (https://github.com/software-gardening/almanack) brings these metaphors of Software Gardening to reality. The Almanack offers practical tools, insights, and strategies for creating sustainable software ecosystems. It provides guidance to solve today’s software development challenges. We conceived the Almanack out of a need to strengthen software ecosystems, reduce proliferation of fragile software, and stop exorbitant waste in scientific software development. With the Almanack, we aim to bring long-term software sustainability to the forefront of and prime consideration for scientific software development. The Almanack provides educational technology to equip software developers with knowledge and pragmatic, functional tools that lead to software that is more robust to the demands of time.

We present the Software Gardening Almanack as two open-source components: a digital book and a Python package (Figure 3). First, the book, available through GitHub as a Jupyter Book, acts as a learning guide, providing a curriculum of sustainable software development practices. It provides conceptual and practical advice on sustainable software development practices, illustrated with real-world examples.

Figure 4. The Almanack Python package may be used to find metrics associated with a specific repository.

Second, the Python package, available on PyPI, transforms these ideas into software sustainability reports and software linting checks. Developers install the Software Gardening Almanack package and can immediately analyze any repository code base, which will guide their efforts toward developing software robust to decay (Figure 4). This dual approach of education combined with applied learning ensures that the Almanack not only informs but also empowers developers to act, and, when taken together, improve the overall state of scientific software.

Figure 5. A repository may be analyzed using the Almanack Python package to gather a report of metrics or perform a software linting style check of the repository.

The Python package provides two core capabilities: a JSON-based report of sustainability metrics and a software linting-style check for specific metrics (Figure 5). The report provides specific metadata and metrics for the repository alongside descriptions of these metrics. The software linting check assesses if the repository is following best software development practices. We have configured the check to run alongside continuous integration and deployment (CI/CD) tools to automatically check code as it is changed. The Python package can be executed by any Python interpreter, but also as a command line interface (CLI). We apply the Almanack Python package to the Almanack book itself both through CI/CD for real-time development, as well as in Almanack tutorials, which you can run through this Google Colab notebook.

A deep dive into the Almanack and practical use cases

The Almanack helps developers cultivate sustainable software ecosystems. It implements several sustainability metrics and checks, which promotes sustainable software development. One of these metrics measures Shannon Entropy¹⁴, a concept derived from information theory that quantifies unpredictability and complexity in a given system (Formula 1).

Formula 1. Shannon Entropy

Originally used to measure how much information is required to describe a state of a variable, we apply Shannon’s Entropy formula to software by analyzing code changes. This idea was originally proposed by Hassan¹⁵ in 2009, and we directly implement this metric within the Software Gardening Almanack. In our system, entropy reveals complexity across a project's history. High entropy indicates irregular or unpredictable code modifications, which fragilize projects, making them more expensive to maintain and prone to future error.¹⁵ In contrast, low entropy suggests more consistent and structured software development, where changes are less likely to cause unexpected failure.

To explore software entropy empirically, we collected and analyzed about 10,000 repositories referenced in PubMed articles since 2011. In our search we also collected GitHub metadata such as commit history, stars, forks, issues, primary programming language, and more. This metadata gives us insights into software collaboration and engagement, both of which are also key drivers of software sustainability. Using the Almanack, we calculated Shannon's entropy at the file level across commits, normalizing by total lines of code (loc) per repository (Formula 2). This normalization procedure is required for us to compare projects of varying sizes.

Formula 2. Normalized Shannon Entropy per file

Our analysis showed how software entropy relates to software sustainability (Figure 6). Projects with shorter lifespans exhibited higher entropy, likely indicating rapid and unstructured development cycles lacking sustained maintenance. These projects are prone to instability, which can severely hurt long-term use. In contrast, projects with lower entropy and higher community engagement enjoyed a longer lifespan. We observed many other interesting trends, detailed through a “Seed Bank” notebook within the Software Gardening Almanack book content. Overall, this application shows how entropy can serve as a quick and valuable indicator of software sustainability, while also, importantly, providing insights into the causes of software decay.

Figure 6. Relationships between software entropy, time, and community engagement. In a sample of about 10,000 GitHub repositories referenced in published scientific articles indexed on PubMed, we find that low software entropy is positively associated with sustainability and community engagement through (left) open GitHub issues and (right) number of GitHub forks.

Proactive software maintenance using Software Gardening practices will reduce entropy and lead to more long-lasting software. Left unmanaged, high entropy causes software decay. In other words, the Almanack identifies entropy hotspots, while they’re being developed, that may require targeted maintenance. Similar to an overgrown garden, these hotspots require attention through pruning, such as refactoring and restructuring, to preserve the project sustainability.

Future harvests

Figure 7. Our Almanack roadmap includes the development of a reusable GitHub Action, developing and testing an empirically defined software sustainability score, and integrating checks into community-driven projects to improve scientific communication and impact, such as openRxiv.

Looking ahead, the Almanack is poised to expand impact (Figure 7). We will continue to implement new metrics, including a sustainability score. We will also develop other technical features, such as a GitHub Action, and integration technology for embedding with scientific communication platforms like openRxiv to automatically assess software and analysis repositories that are associated with posted preprints. These innovations will put the Almanack into the hands of those who can benefit most: researchers, developers, and educators who are shaping the future of scientific software.

Let’s garden together

The Software Gardening Almanack is more than a toolkit; it’s a call to action. It invites software developers to rethink how they approach software, not as a static product but as a living, evolving ecosystem. By embracing the principles of gardening—nurturing growth, fostering collaboration, and planning for the future—we can create software that not only thrives in the moment, but also stands the test of time.

So, let’s garden together. Explore the Almanack, join the community, and help cultivate a better future for scientific software!

Acknowledgements

The Software Gardening Almanack was made possible through the support of a Better Scientific Software (BSSw) Fellowship awarded to Dave Bunten. The BSSw Fellowship empowers leaders to advance scientific software quality, sustainability, and community engagement. Through this fellowship, the project received the resources and network needed to promote best practices in software development, fostering a more maintainable and collaborative ecosystem for scientific computing.

We are also deeply grateful to the following individuals and organizations whose support has been instrumental in the creation of the Software Gardening Almanack:

• Faisal Alquaddoomi
  
• Vincent Rubinetti
  
• Cameron Mattson
  
• Erik Serrano
  
• Members of the Way Lab at the University of Colorado Anschutz Medical Campus (https://www.waysciencelab.com/)
  
• Department of Biomedical Informatics within the School of Medicine at the University of Colorado Anschutz Medical Campus (https://medschool.cuanschutz.edu/dbmi)
  
• Aditi Gopalan, Jineta Banerjee and The Multi-Consortia Coordinating (MC²) Center for Cancer Biology managed by Sage Bionetworks (https://sagebionetworks.org/community/mc2-center)
  
• Jonathan Starr and The Map of Open Source Science (MOSS) managed by NumFocus (https://www.opensource.science/moss)
  
• Better Scientific Software (BSSw) (https://bssw.io)
  
• Sustainable Horizons Institute (https://shinstitute.org)

Figure credits

Figure 1 Daubigny, Charles-François, French Orchard at Harvest Time (Le verger). Retrieved from Wikimedia Commons.

Author bios

Dave Bunten is a Research Software Engineer with the Department of Biomedical Informatics at the University of Colorado Anschutz. He has over a decade of experience in the field of software development through various roles in his career. His keen interest in software design, collaboration, and innovation has driven him to explore various areas of the field. He is particularly passionate about research data engineering, in-memory data flow, and scientific software.

Will Davidson is a Computer Science student at the University of Colorado Boulder and an incoming Developer at Capital Group. Previously, he interned at the University of Colorado Anschutz Medical Campus, where he contributed to the Software Gardening Almanack. His work focused on software entropy analysis, Git-based metrics, and developing tools to support long-term software resilience. He is passionate about open-source development and creating innovative, high-impact software that addresses complex challenges.

Gregory P. Way is an Assistant Professor in the Department of Biomedical Informatics at the University of Colorado Anschutz. His lab develops methods and software for analyzing large biomedical datasets, most often in the context of drug screens for rare diseases. He believes that high-performance software facilitates science and that we could not make the next discoveries in treating human diseases without software engineers. The sustainability of software is essential to maintaining scientific progress and reducing human suffering.

References

• ¹Heroux, M. et al. Basic Research Needs in The Science of Scientific Software Development and Use: Investment in Software Is Investment in Science. (2023) doi:10.2172/1846009.
• ²Afiaz, A. et al. Evaluation of software impact designed for biomedical research: Are we measuring what's meaningful? Preprint at https://doi.org/10.48550/arXiv.2306.03255 (2023).
• ³Sochat, V. The Stanford Software Survey, 2020. Zenodo https://doi.org/10.5281/ZENODO.4464625 (2021).
• ⁴US Research Software Engineer Association & IEEE Computer Society. Research Software Engineers: Creating a Career Path—and a Career. Preprint at https://doi.org/10.5281/ZENODO.10073232 (2023).
• ⁵Krasner, H. Cost of Poor Software Quality in the U.S.: A 2022 Report. https://www.it-cisq.org/the-cost-of-poor-quality-software-in-the-us-a-2022-report/ (2022).
• ⁶K. Hinsen, Dealing With Software Collapse, in Computing in Science & Engineering, vol. 21, no. 3, pp. 104-108, 1 May-June 2019, doi: 10.1109/MCSE.2019.2900945.
• ⁷Bunten, D., Davidson, W., Alquaddoomi, F., Rubinetti, V. & Way, G. The Software Gardening Almanack. Zenodo https://doi.org/10.5281/ZENODO.14765834 (2025).
• ⁸Cosden, I. A., McHenry, K. & Katz, D. S. Research Software Engineers: Career Entry Points and Training Gaps. (2022) doi:10.48550/ARXIV.2210.04275.
• ⁹GitHub Staff. Octoverse: AI leads Python to top language as the number of global developers surges. GitHub Blog https://github.blog/news-insights/octoverse/octoverse-2024/ (2024).
• ¹⁰He, H. et al. 4.5 Million (Suspected) Fake Stars in GitHub: A Growing Spiral of Popularity Contests, Scams, and Malware. Preprint at https://doi.org/10.48550/arXiv.2412.13459 (2024).
• ¹¹Michael Fire, Carlos Guestrin, Over-optimization of academic publishing metrics: observing Goodhart's Law in action, GigaScience, Volume 8, Issue 6, June 2019, giz053, https://doi.org/10.1093/gigascience/giz053
• ¹²Bunten, D. & Way, G. P. Long-Term Software Gardening Strategies for Cultivating Scientific Development Ecosystems. Better Scientific Software (BSSw) Blog https://bssw.io/blog_posts/long-term-software-gardening-strategies-for-cultivating-scientific-development-ecosystems (2023).
• ¹³Wilson G, Bryan J, Cranston K, Kitzes J, Nederbragt L, Teal TK (2017) Good enough practices in scientific computing. PLoS Comput Biol 13(6): e1005510. https://doi.org/10.1371/journal.pcbi.1005510
• ¹⁴C. E. Shannon, A mathematical theory of communication, in The Bell System Technical Journal, vol. 27, no. 3, pp. 379-423, July 1948, doi: 10.1002/j.1538-7305.1948.tb01338.x.
• ¹⁵Hassan, A. E. Predicting faults using the complexity of code changes. in 2009 IEEE 31st International Conference on Software Engineering 78–88 (IEEE, Vancouver, BC, Canada, 2009). doi:10.1109/ICSE.2009.5070510.