-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathprinciples.qmd
142 lines (100 loc) · 12.7 KB
/
principles.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
---
title: 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.
[^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)](https://doi.org/10.5281/zenodo.3997801) for a more in-depth analysis.
Our blueprints is defined by 7 key aspects/principles:
- [Software development as co-creation](#software-development-as-co-creation)
- [Lean and Agile collaboration framework](#lean-and-agile-collaboration-framework)
- [Decentralizing code ownership](#decentralizing-code-ownership)
- [Code reviews](#code-reviews)
- [Documentation](#documentation)
- [Being part of the OSS landscape](#being-part-of-the-oss-landscape)
- [Community health](#community-health)
The mindmap below provides an overview of the blueprints content. Please refer to the respective sections for details and explanations.
This page is focused on general principles of the project and for each one of these principles, we link to other sections of the book detailing the practical application of these principles in our processes.
## Software development as co-creation
Useful software development is unlikely to be achieved by developers alone: rather, it needs to be co-created by users and developers. Some key principles of this co-creation include:
- Users provide key inputs 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 should be involved from the start of a project, and provide continuous feedback as the project develops
- User contributions need to be valued and acknowledged clearly
- User contributions need to be 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
::: {.callout-tip title="Read more about this principle in application"}
- [What should the first 100 lines of code written during an epidemic look like?](https://epiverse-trace.github.io/posts/100days-workshop/)
:::
## Lean and Agile collaboration framework
The main objective of our collaboration framework will be to optimize interactions between users and developers. We thus naturally embrace the agile philosophy in which projects progress iteratively through short cycles focussing 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 also 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 a few 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 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.
## 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 Rstudio](https://style.tidyverse.org/); consider using static code analysis *e.g.* [lintr](https://github.com/r-lib/lintr) or [styler](https://styler.r-lib.org/) 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](https://testthat.r-lib.org/)), coverage ([covr](https://covr.r-lib.org/)) and continuous integration using github actions ([usethis](https://usethis.r-lib.org/))
- Contribute to the code base by [PRs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) with well-identified processes for code reviews (see dedicated section below)
- Conduct occasional audits of the entire code base by other team members
::: {.callout-tip title="Read more about this principle in application"}
- [Git branching and merging process](git-branching-merging.qmd)
- [Ensuring and showcasing the statistical correctness of your R package](https://epiverse-trace.github.io/posts/statistical-correctness/)
- [Improving the C++ code quality of an Rcpp package](https://epiverse-trace.github.io/posts/lint-rcpp/)
:::
## Code reviews
Code reviews are not just a way to improve overall code quality: they are a key mechanism through which team members can share programming knowledge, better understand existing code bases, and standardize coding practices.
Key principles include:
- Consider code reviews as a non-hierarchical exercise, performed by all members of the developers team.
- Understand that code reviews are a great opportunity for training and collaboration
- Consider Alex Hill’s [quadrant of code reviews](https://www.alexandra-hill.com/2018/06/25/the-art-of-giving-and-receiving-code-reviews/) when conducting reviews and treat separately:
- Most code quality issues can be solved with automation (*e.g.* styling with [lintr](https://lintr.r-lib.org/), [styler](https://styler.r-lib.org/), or [goodpractice](https://mangothecat.github.io/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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request).
- Use code walk-throughs ahead of reviews to facilitate the review process.
- Prefer small reviews to large ones
- Conduct occasional audits of the entire code base
::: {.callout-tip title="Read more about this principle in application"}
- [Improving the C++ code quality of an Rcpp package](https://epiverse-trace.github.io/posts/lint-rcpp/)
- [Code review](code-review.qmd)
:::
## Documentation
Consistent, high quality, and accessible documentation is key to adopting software tools. Key consideration for delivering good documentation include:
- Consider documentation on the same level as code, rather than as an afterthought
- Use the [Diataxis framework](https://diataxis.fr/) to distinguish: tutorials, how-to guides, reference manuals, and explanatory material
- Generate documentation dynamically using standard tools: [roxygen2](https://roxygen2.r-lib.org/) for basic documentation, [rmarkdown](https://rmarkdown.rstudio.com/docs/) for vignettes, [pkgdown](https://pkgdown.r-lib.org/) for websites
- 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](https://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
## 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](https://opensource.org/licenses/MIT)) for our tools
- We build upon open data standards (*e.g.* [FHIR](https://fhir.org/), [HDX](https://data.humdata.org/)) 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](https://digitalpublicgoods.net/) 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. For instance, we may want to avoid reusing GPL code if our project uses MIT, since we would then have to change our license to GPL. See [this article](https://www.gnu.org/licenses/license-list.html) 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
::: {.callout-tip title="Read more about this principle in application"}
- [From disconnected elements to a harmonious ecosystem: the Epiverse-TRACE project](https://epiverse-trace.github.io/slides/harmonious-ecosystem/)
- [Converting your R Function to an S3 Generic: benefits, pitfalls & design considerations](https://epiverse-trace.github.io/posts/s3-generic/)
- [Extending Data Frames: Creating custom classes and {dplyr} compatibility](https://epiverse-trace.github.io/posts/extend-dataframes/)
:::
## 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](https://docs.google.com/document/d/e/2PACX-1vRcwl2uaKdEQT5iS-9MroDMKsd81oR8v1gdlY1kHTTjgGEbLKfcWxtdrkvVRhJJGQalsgC1A4K4YiDe/pub) for our community members to highlight and support our values
- Give proper recognition to all [types of contributions](https://chaoss.community/metric-types-of-contributions/), which go beyond coding and can take diverse forms *e.g.* testing, input on tool design, training
- Use [CHAOSS metrics](https://chaoss.community/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