General principles

The recommendations below aim to cover the most important aspects of the development of Epiverse-TRACE. For simplicity, we distinguish users from developers according to the type of contributions they make to a software project: developers create content (code and documentation), while users advise, test, and provide feedback on content 1. User-bases will be project-dependent but would typically include field epidemiologists or public health officers.

Our blueprints are defined by 7 key aspects/principles:

The mindmap below provides an overview of the blueprints content. Please refer to the respective sections for details and explanations.

A mindmap summary of the 7 principles underpinning Epiverse-TRACE. At the center of the mindmap is the Epiverse-TRACE hex logo. It is surrounded by 7 boxes: Software development as co-creation, Lean and Agile collaboration framework, Decentralizing code ownership, Code reviews, Documentation, Being part of the OSS landscape, Community health. Each of these seven boxes is then linked to a series of smaller boxes containing key features of the principle, also detailed in the rest of this page.

Mindmap representation of the 7 principles presented below and their key features

This page is focused on general principles of the project. For each of these principles, we link to other sections of the book detailing the practical application of these principles in our processes.

Additionally, these principles are implemented in a GitHub template repository: epiverse-trace/packagetemplate. This template repository aims to facilitate the adoption of the presented standards and provide a quick starting point for new packages. Further information about the template repository is available in the dedicated wiki.

Software development as co-creation

Useful software development is co-created by users and developers – it unlikely to be achieved by developers alone.

Some key principles of this co-creation include:

  • Users provide key input on the identification and prioritization of minimal viable products (MVPs), which can be defined as the smallest increment of the project delivering value for the user
  • Users are involved from the start of a project and provide continuous feedback as the project develops
  • User contributions are valued and acknowledged clearly
  • User contributions are an intrinsic part of the collaboration framework (see section below), with dedicated events such as brainstorming sessions or product reviews
  • Co-creation can also take the form of pair-programming to combine domain experts and developers
Read more about this principle in application

Lean and Agile collaboration framework

The main objective of our collaboration framework is to optimize interactions between users and developers. We embrace the agile philosophy, in which projects progress iteratively through short cycles. During those cycles, focus is on delivering and reviewing MVPs. We foresee that each cycle should have three main phases:

  1. Planning: users and developers write a backlog of tasks to complete, identify top priorities, and define which MVPs will be worked on in the production phase
  2. Production: developers produce MVPs; if pair-programming is used, users could be involved at this stage too
  3. Review: presentation of MVPs and collection of feedback; the backlog is updated accordingly; this is also the opportunity for a retrospective assessment of the process: What was done well? What caused problems? How can the team improve the work process?

To maximize agility, we recommend adopting the lean principle in which the amount of work in progress (WIP) at any time is minimized. In other words, it is more efficient to work on fewer MVPs and deliver value quickly, rather than working on many MVPs at the same time, resulting in a lot of WIP and low completion rates.

We recommend using Kanban boards (which can be created through the Projects tab on GitHub) to keep track of progress, and as a tool for identifying long-lasting WIP, likely indicative of blockage or issues which need addressing. These boards should be fully public to encourage and facilitate external visibility and contributions.

The Epiverse-TRACE agile strategy is graphically represented as a workflow composed of 7 steps connected by arrows. The steps are: 1. Pitch the idea; 2. Seek feedback; 3. Create the design document; 4. Seek feedback; 5. Create repository from packagetemplate; 6. Start initial development; 7. Seek feedback on MVP. The figure has a cartoonish style, with lilac and purples hues and was create by Melissa Avila during the Epiverse-TRACE Summit 2023 in Bogotá.

The Epiverse-TRACE agile workflow for new projects, as recorded by Melissa Avila during the Epiverse-TRACE Summit 2023 in Bogotá, CC BY.
Read more about this principle in application

Decentralizing code ownership

The sustainability of open source software (OSS) projects increases with the number of developers who understand the code base enough to make contributions. While there is always a need for a single official maintainer, we will aim at decentralizing code ownership as much as possible, using a series of practices:

  • Avoid siloed codebase: have team members move across different projects
  • Aim for code clarity by following coding standards established by the tidyverse team at Posit PBC; consider using static code analysis e.g. lintr or styler to ensure adherence with standards
  • Use modular, reusable code, with small, well-documented functions having a clear purpose
  • Use canonical, widely used data structures and tools where possible
  • Write tests for every function so that other developers can identify easily what it is expected to do, and where/how it is expected to fail
  • Implement extensive automated testing, aiming for maximum code coverage, to help identify potential issues in new contributions; we recommend using existing R standards for testing (testthat), coverage (covr) and continuous integration using github actions (usethis)
  • Contribute to the code base by PRs with well-identified processes for code reviews (see dedicated section below)
  • Conduct occasional audits of the entire code base by other team members
Read more about this principle in application

Code reviews

Code reviews are a way to improve overall code quality and a key mechanism through which team members can share programming knowledge, better understand existing code bases, and standardize coding practices.

Key principles include:

  • Code reviews are performed by all members of the developers team (regardless of hierarchy).
  • Code reviews are an opportunity for training and collaboration
  • Consider Alex Hill’s quadrant of code reviews when conducting reviews and treat separately:
    • Most code quality issues can be solved with automation (e.g. styling with lintr, styler, or goodpractice).
    • Non-conflictual, factual issues can be quickly agreed on (e.g. missing tests, typos in the documentation).
    • Spend time to discuss high-conflict, high-reward items, and take a collaborative approach to identifying solutions.
  • Use pair-programming sessions when developing features to foster a sense of code co-ownership and peer learning.
  • Make code reviews an intrinsic part of the contribution workflow: they are typically performed as part of the PR review process.
  • Code walk-throughs facilitate the review process.
  • Prefer small reviews to large ones.
  • Conduct occasional audits of the entire code base.
Read more about this principle in application

Documentation

Consistent, high quality, and accessible documentation is key to adopting software tools.

Key considerations for delivering quality documentation include:

  • Consider documentation on the same level as code, rather than as an afterthought
  • Use the Diataxis framework to distinguish: tutorials, how-to guides, reference manuals, and explanatory material
  • Generate documentation dynamically using standard tools: roxygen2 for basic documentation, rmarkdown for vignettes, pkgdown for websites
  • Generate tutorial content using The Carpentries Workbench, which provides a distinctive approach to organizing learning materials for both learners and instructors
  • Provide user-friendly cheatsheets in html and pdf
  • Provide interactive content (tutorials, how-to guides) with no need for installing dependencies locally using mybinder.org
  • Write documentation assuming minimum R literacy and prior knowledge
  • Content should clearly state requirements, objectives, and value for the user
  • Aim to provide translations for the most common languages
  • We provide automated blog posts for major and minor releases. Code owners may occasionally decide to release patch blogs if the patch is critical.

Being part of the OSS landscape

As an open-source initiative, Epiverse-TRACE will benefit from numerous other OSS projects. In becoming part of the OSS landscape, we will observe a few principles:

  • We use open-source, liberal licenses (e.g. MIT) for our tools
  • We build upon open data standards (e.g. FHIR, HDX) and develop interoperability with existing data resources and Health Information Management Systems (HIMS)
  • We develop tools for social impact, in compliance with Digital Public Goods standard
  • We take, but we give back: we use and build upon OSS projects, but we give back to the community by developing new OSS tools, and contributing to existing ones
  • We prioritize contributions to existing projects over forks, and forks over project duplications
  • When code re-use is needed, we duly credit authors and point to the source, and invite authors as contributors on our project. We give credits by prefacing reused code by a comment e.g.: // credits: this code was adapted from SOURCE_URL, where SOURCE_URL is the URL we obtained the code from (e.g. stackoverflow, etc.). Using a fixed syntax for credits can be used to summarize such contributions programmatically.
  • When reusing licensed code, we ensure that third-party licenses are compatible with our project’s license. See this article by the Free Software Foundation for more information on free software licenses.
  • We prioritize the integration of existing tools over development from scratch of new tools
  • We welcome external contributions and promote transparency on all our projects
  • When contributing to external projects, we observe their contributor code of conduct
Read more about this principle in application

Community health

The success of an OSS project like Epiverse-TRACE relies heavily on the quality and frequency of interactions between members of our community of users and developers. We will ensure a healthy community through the following principles:

  • Foster a welcoming environment which promotes diversity and inclusiveness
  • Provide a code of conduct for our community members to highlight and support our values
  • Give proper recognition to all types of contributions, which go beyond coding and can take diverse forms e.g. testing, input on tool design, training
  • Use CHAOSS metrics to monitor community health and reflect our values
  • Use occasional surveys to monitor aspects of community health which cannot be captured automatically
  • Invest in mentoring programs to strengthen capacity where it is most needed
Read more about this principle in application

  1. Note that users and developers are not exclusive or static roles. Community members are expected to have various levels of involvement with the project, evolving in a non-linear fashion with time, and in a complex way that cannot be fully captured by simple terms such as user & developer. This is beyond the scope of this book but you can read Woodley, Lou & Pratt, Katie. (2020) for a more in-depth analysis.↩︎