From d3260d8a797ca706a2676bf2f3faf7711578bf75 Mon Sep 17 00:00:00 2001 From: Anders E Bilgrau Date: Wed, 1 Mar 2023 20:35:58 +0100 Subject: [PATCH] Improve section re #20 --- using.qmd | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/using.qmd b/using.qmd index db8e8bf..17b86f9 100644 --- a/using.qmd +++ b/using.qmd @@ -1,8 +1,12 @@ # Using open source +The following section is a non-exhaustive discussion of topics relevant when using open-source data science projects. + ## What is the open-source health of the package? -The communities that maintain and build open-source packages are diverse, and there are no set conventions on how they are maintained, resourced, and governed. There are no universal magic metrics to summarise whether an OS project is _'healthy'_; for example if a project has had no activity for 12 months, is that because the product has been abandoned/superseded, or could it be it had a small well-defined scope and is now stable and feature complete? The following section is a non-exhaustive discussion of topics relevant when using open-source data science projects. +The communities that maintain and build open-source packages are diverse, and there are no set conventions on how they are maintained, resourced, and governed. There are no universal metrics to determine if an OS project is _'healthy'_. Health _indicators_ such as project activity, apparent use, clear governance, and active maintainers are just _that_. + +A project with no activity for years, for example, might be simply be considered 'done' and not necessarily because the project has been abandoned/superseded. 'Done' in the sense of being stable and feature complete perhaps due to a small and well-defined scope. ## How can I see the activity of an open-source project? @@ -14,15 +18,17 @@ Some sites like [openpharma.pharmaverse.org](http://openpharma.pharmaverse.org) ### How active are the community behind a project? -The activity on a project does not tell you the quality and extent of use of a project. Two examples are: +The activity on a project alone does not tell you the quality and extent of use of a project. Two examples are: - A project could have almost no active community in terms of recent contributions or response to issues, much like the R package [survival](https://github.com/therneau/survival), yet be a stable and critical package in R installations. - A project could also have no activity as it has been abandoned after or before it reached v1.0. -The community behind a project is also not limited to the people that contribute code. Users can also engage with a project via giving feedback via mechanisms like GitHub issues, emailing authors or engaging in discussions on GitHub issues. @fig-teal is an example of an issue page for the teal R package. The figure shows that teal has 24 open issues, and 266 closed issues. Small speech bubbles on the right of the figure show discussion have occurred on some issues. By looking through the issues, subjective impressions on community health can be made, for instance whether it's a few people giving feedback and one person developing, does it have stale issues no-one replies to, or does it have a lively community engaged in discussion and coordination. +The community behind a project is also not limited to the people that contribute code. Users can also engage with a project via giving feedback via mechanisms like GitHub issues, emailing authors or engaging in discussions on GitHub issues. @fig-teal is an example of an issue page for the teal R package. The figure shows that teal has 24 open issues, and 266 closed issues. Small speech bubbles on the right of the figure show discussion have occurred on some issues. ![An example screenshot of the R package teal's issue page](assets/teal.png){#fig-teal} +By looking through issues, subjective impressions on community health can be made. Is it a few people giving feedback and one person developing? Does it have stale issues no-one replies to? Or does it have a lively community engaged in discussion and coordination? + Packages can also be open sourced without having the place they develop the code exposed to the general public. An example is the [randomForest](https://www.stat.berkeley.edu/~breiman/RandomForests/) package, which is an open sourced (GPL-2/3) R package where the source code of the releases is open sourced for use, but the package authors do not give users access to view the place where they develop code. This does not mean the quality of the code is inferior, but does indicate there is an additional barrier to engaging with the package development as the first step would be to contact the authors. Some things to consider when trying to establish the activity of a community are: