Update README.md

penyuan · penyuan · commit bace8a6aac9c · 2022-08-14T14:28:57.000+01:00
Minor fixes.
diff --git a/README.md b/README.md
@@ -8,13 +8,14 @@
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](./CODE_OF_CONDUCT.md)
 [![GitHub license](https://img.shields.io/github/license/OPEN-NEXT/wp2.2_dev.svg?style=flat)](./LICENSE)
 
-*Initial proof-of-concept of data-mining backend for an open source development status dashboard*
+***Demonstrator** data-mining backend for an open source development status dashboard*
 
 Targeted at hosters of version control platforms (such as [Wikifactory](https://wikifactory.com/), [GitLab](https://gitlab.com/), or [GitHub](https://github.com/)), this Python backend program mines open source hardware repositories for metadata and calculates metrics based on it. This backend exposes a representational state transfer ([REST](https://en.wikipedia.org/wiki/Representational_state_transfer)) application programming interface ([API](https://en.wikipedia.org/wiki/Web_API)) where requests for those metrics can be made.
 
 ***This software is not for general consumers to just "double click" on and install on their devices***.
 
-**Please see the [Install](#install) and [Usage](#usage) sections to get up and running with this tool**. For more details on its background and design considerations, please see the [Background](#background), ~~[Design notes](#design-notes), and [Future work](#future-work) sections. There is also a detailed [step-by-step walkthrough](docs/usage-example.md).~~
+**Please see the [Install](#install) and [Usage](#usage) sections to get up and running with this tool**.
+
 ## Table of Contents
 
 - [OSD status dashboard _(wp2.2\_dev)_](#osd-status-dashboard-wp22_dev)
@@ -23,13 +24,12 @@ Targeted at hosters of version control platforms (such as [Wikifactory](https://
   - [Install](#install)
     - [Running from source](#running-from-source)
     - [Deploy as container](#deploy-as-container)
-      - [Heroku example](#heroku-example)
+      - [Heroku deployment example](#heroku-deployment-example)
       - [Fly.io example](#flyio-example)
   - [Usage](#usage)
     - [Making requests to the REST API](#making-requests-to-the-rest-api)
     - [API response format](#api-response-format)
     - [Custom Wikifactory URLs](#custom-wikifactory-urls)
-  - [Design notes](#design-notes)
   - [Maintainers](#maintainers)
   - [Contributing](#contributing)
   - [Acknowledgements](#acknowledgements)
@@ -41,18 +41,12 @@ Targeted at hosters of version control platforms (such as [Wikifactory](https://
 
 [OPENNEXT](https://opennext.eu/) is a collaboration between 19 industry and academic partners across Europe. Funded by the [European Union](https://europa.eu/)'s [Horizon 2020](https://ec.europa.eu/programmes/horizon2020/) programme, this project seeks to enable small and medium enterprises (SMEs) to work with consumers, makers, and other communities in rethinking how products are designed and produced. [Open source hardware](https://www.oshwa.org/definition/) is a key enabler of this goal where the design of a physical product is released with the freedoms for anyone to study, modify, share, and redistribute copies. These essential freedoms are based on those of [open source software](https://opensource.org/osd), which is itself derived from [free software](https://www.gnu.org/philosophy/free-sw.en.html) where the word free refers to freedom, *not* free-of-charge. When put in practice, these freedoms could potentially not only reduce proprietary vendor lock-in, planned obsolescence, or waste but also stimulate novel – even disruptive – business models. The SME partners in OPENNEXT are experimenting with producing open source hardware and even opening up the development process to wider community participation. They produce diverse products ranging from [desks](https://stykka.com/), [cargo bike modules](http://www.xyzcargo.com/), to a [digital scientific instrument platform](https://pslab.io/) (and [more](https://opennext.eu/project-team/#sme)).
 
-Work package 2 of OPENNEXT is gathering theoretical and practical insights on best practices for company-community collaboration when developing open source hardware. This includes running [Delphi studies](https://www.edelphi.org/) to develop a maturity model to describe the collaboration and developing a precise definition for what the "source" is in open source hardware. In particular, task 2.2 in this work package is developing a project status dashboard with "health" indicators showing the evolution of a project within the maturity model; design activities; or progress towards success based on project goals.
-
-~~To that end, the month 18 deliverable for task 2.2 is focused on establishing the underlying "behind the scenes" infrastructure to mine data about open source hardware projects from version control repositories that they are hosted on (`osmine`). The Python scripts in this repository currently query the public [application programming interfaces](https://en.wikipedia.org/wiki/API) (APIs) of [GitHub](https://www.github.com/) and [Wikifactory](https://www.wikifactory.com/). Both platforms host version control repositories with the latter having a focus on supporting open source hardware projects. There is also a barebones proof-of-concept user-facing demonstration dashboard (`osdash`) which computes core metrics from the mined data and presents interactive visualisations. This dashboard is only to show that the underlying data could be displayed, and is not meant to confer immediate usefulness at this time.~~
+Work package 2 (WP2) of OPENNEXT is gathering theoretical and practical insights on best practices for company-community collaboration when developing open source hardware. This includes running [Delphi studies](https://www.edelphi.org/) to develop a maturity model to describe the collaboration and developing a precise definition for what the "source" is in open source hardware. In particular, task 2.2 in this work package is developing a demonstration project status dashboard with "health" indicators showing the evolution of a project within the maturity model; design activities; or progress towards success based on project goals. Details of the dashboard's technical architecture are described in the deliverable 2.5 (D2.5) report.
 
-To be clear, this deliverable ***is***: Designed to be deployed on a server operated by version control platforms such as Wikifactory or GitHub.
+This repository contains the backend code for D2.5 and to be clear, this deliverable ***is***: Designed to be deployed on a server operated by version control platforms such as Wikifactory or GitHub.
 
 This deliverable ***is not***: For general end-users to install on consumer devices and "double click" to open.
 
-There are other excellent open source software for open source project analytics and data visualisation, with [Grimoirelab](https://chaoss.github.io/grimoirelab/) being a prime example. However, the full Grimoirelab pipeline requires a full server stack necessitating advanced skills in heavy-duty (but potentially complicated) web technologies such as [Kibana](https://www.elastic.co/products/kibana) or [Elastisearch](https://www.elastic.co/products/elasticsearch). This project aims to create a lighter, more focused solution needing only the use of Python.
-
-This documentation aims to demonstrate practices that facilitate design reuse, including of this repository. In addition to the [Install](#install) and [Usage](#usage) sections that increase reproducibility, ~~[Design notes](#design-notes) and [Future work](#future-work) communicate the thought process and lessons-learned while developing the dashboard. Together, they constitute an intangible body of "know-how" that is very often undocumented. For example, motivations for the internal data model or the approach to compressing data at the end of the section [Internal data structure](#internal-data-structure) which reduces disk usage are of practical benefit. But "snippets" of practical experience like these are seldom recorded.~~
-
 In addition, this repository aims to follow international standards and good practices in open source development such as, but not limited to: 
 
 * [SDPX 3](https://spdx.dev/) compliance with a [LICENSE](./LICENSE) file (also see [License](#license) section)
@@ -64,7 +58,7 @@ In addition, this repository aims to follow international standards and good pra
 
 ## Install
 
-This section assumes knowledge of Python, Git, and using a GNU/Linux-based server including installing software from package managers and running a terminal session.
+This section assumes knowledge of [Python](https://www.python.org/), [Git](https://git-scm.com/), and using a GNU/Linux-based server including installing software from package managers and running a terminal session.
 
 **Note:** This software is designed to be deployed on a server by system administrators or developers, not on generic consumer devices.
 
@@ -86,7 +80,7 @@ A [GitHub personal access token](https://docs.github.com/en/github/authenticatin
 
 ### Running from source
 
-The code can be run from source and has been tested on updated versions of GNU/Linux server operating systems including [Red Hat Enterprise Linux](https://redhat.com/en/technologies/linux-platforms/enterprise-linux) 8.5. While effort has been made to keep the Python scripts platform-agnostic, they have not been tested under other operating systems such as [BSD](https://en.wikipedia.org/wiki/Berkeley_Software_Distribution)-derivatives, [Apple macOS](https://www.apple.com/macos/) or [Microsoft Windows](https://www.microsoft.com/windows/) as they are rarely used for hosting code such as this (especially the latter two).
+The code can be run from source and has been tested on updated versions of GNU/Linux server operating systems including [Red Hat Enterprise Linux](https://redhat.com/en/technologies/linux-platforms/enterprise-linux) 8.5. While effort has been made to keep the Python scripts platform-agnostic, they have not been tested under other operating systems such as [BSD](https://en.wikipedia.org/wiki/Berkeley_Software_Distribution)-derivatives, [Apple macOS](https://www.apple.com/macos/) or [Microsoft Windows](https://www.microsoft.com/windows/) as they - especially the latter two- are rarely used for hosting code such as this.
 
 On your server, with the tools [`git`](https://git-scm.com/) and [`pip`](https://pip.pypa.io/) installed, run the following commands in a terminal session to retrieve the latest version of this repository and prepare it for development and running locally (usually for testing): 
 
@@ -113,7 +107,7 @@ This means the server API is up an running, and should be accessible on your loc
 
 ### Deploy as container
 
-There is a [`Dockerfile`](./Dockerfile) in this repository that defines a [container](https://en.wikipedia.org/wiki/OS-level_virtualization) within which this program can run.
+There is a [`Dockerfile`](./Dockerfile) in this repository that defines a [container](https://en.wikipedia.org/wiki/OS-level_virtualization) within which this code can run.
 
 To build and use the container, you need to have programs like [Podman](https://podman.io) or [Docker](https://en.wikipedia.org/wiki/Docker_(software)) installed.
 
@@ -133,7 +127,7 @@ podman run --env PORT=8000 --env GITHUB_TOKEN=[token] -p 127.0.0.1:8000:8000 -d
 
 Where `token` is the 40 character alphanumeric string of your GitHub API personal access token. It is in the form of "ghp_2D5TYFikFsQ4U9KPfzHyvigMycePCPqkPgWc".
 
-#### Heroku example
+#### Heroku deployment example
 
 The image built this way can be pushed to cloud hosting providers such as [Heroku](https://www.heroku.com/). With Heroku as an example: 
 
@@ -165,11 +159,11 @@ A demo of this is hosted on Heroku with this API endpoint:
 https://wp22dev.herokuapp.com/data
 ```
 
-This demo instance will go into a sleep state after a period of inactivity. If your API calls to this endpoint is taking more than a few seconds, it might be the demo waking from that state.
+This demo instance will go into a sleep state after a period of inactivity (approximately 30 minutes at time of writing). If your API calls to this endpoint is taking more than a few seconds, it might be the demo waking from that state.
 
 #### Fly.io example
 
-Similar to Heroku, the container image created above can be deployed to an app on [Fly.io](https://fly.io/). Assuming an account has already been created: 
+Similar to Heroku, the container image created above can be deployed to an app on [Fly.io](https://fly.io/). Assuming a Fly.io account has already been created: 
 
 1. Log in to Fly.io in a terminal session: 
 
@@ -211,21 +205,21 @@ Where `token` is the 40 character alphanumeric string of your GitHub API persona
 
 ## Usage
 
-The backend server listens to requests for information about a list of open source hardware (and software) repositories hosted on Wikifactory or GitHub. The GitHub backend is a placeholder for now, but the Wikifactory backend is now accessible.
+The backend server listens to requests for information about a list of open source hardware (and software) repositories hosted on Wikifactory or GitHub.
 ### Making requests to the REST API
 
 [GET requests](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) to the API are formed as [JSON](https://www.json.org/json-en.html) payloads to the `/data` endpoint.
 
 There are two components to each request: 
 
-1. `repo_urls`: An array of strings of repository [URL](https://en.wikipedia.org/wiki/URL)s, such as `https://wikifactory.com/+elektricworks/pikon-telescope`. Currently, metadata retrieval for Wikifactory project URLs is implemented. Each URL is composed of the Wikifactory domain (`wikifactory.com`), space (e.g. `+elektricworks`), and project (e.g. `pikon-telescope`).
+1. `repo_urls`: An array of strings of repository [URL](https://en.wikipedia.org/wiki/URL)s, such as `https://wikifactory.com/+elektricworks/pikon-telescope`. Currently, metadata retrieval for Wikifactory project and GitHub repository URLs are implemented. Each URL is composed of the Wikifactory domain (`wikifactory.com`), space (e.g. `+elektricworks`), and project (e.g. `pikon-telescope`).
 
 2. `requested_data`: An array of strings representing the types of repository metrics desired for each repository. Currently, the following are implemented for Wikifactory projects: 
    1. `files_info`: The numbers and proportions of mechanical and electronic computer-assisted design (CAD), image, data, document, and other file types in the repository.
    2. `files_editability`: Basic information about how "editable" the CAD files are in this repository.
    3. `license`: The license for the repository.
    4. `tags`: Aggregated tags for the repository and any associated with the maintainers of that repsitory.
-   5. `commits_level`: The hash identifier (contribution `id` for Wikifactory projects) and timestamp of each commit to the repository. This can be used to graph the commit activity level in a frontend visualisation. **Note:** This will be based on commits from the first three detected branches in the repository, including the default branch. This is because the time it takes to requests commits across various branches take a long time, and APIs might time out.
+   5. `commits_level`: The hash identifier (contribution `id` for Wikifactory projects) and timestamp of each commit to the repository. This can be used to graph the commit activity level in a frontend visualisation. **Note:** This will be based on commits from the first three detected branches in the repository, including the default branch. This is because the time it takes to requests commits across various branches take a long time, and APIs might time out. Also note that branches are not implemented by Wikifactory, so it will behave as if there is only one branch.
    6. `issues_level`: Similar to `commits_level`, but for all issues in the repository.
 
 The following is an example request that could be sent to the API for three Wikifactory projects: 
@@ -332,15 +326,11 @@ By default, this tool will:
 1. Identify whether a provided repository URL in the JSON request body as a Wikifactory project if it is under the domain `wikifactory.com`
 2. Use the public Wikifactory GraphQL API endpoint at `https://wikifactory.com/api/graphql`
 
-Both can be customised with the following environmental variables: 
+Both can be customised with the following environmental variables during deployment: 
 
 1. `WIF_BASE_URL` - (default: `wikifactory.com`) The base domain used for pattern-matching and identifying Wikifactory project URLs in the JSON request body in the form of `example.com`. If this is customised, then the requested Wikifactory project URLs passed to this tool should also use that domain instead of `wikifactory.com`. Otherwise, an "Repository URL domain not supported" error will be returned.
 2. `WIF_API_URL` - (default: `https://wikifactory.com/api/graphql`) The full URL of the GraphQL API endpoint to make queries regarding Wikifactory projects in the form of `https://example.com[:port]/foo/bar`.
 
-## Design notes
-
-[to be updated]
-
 ## Maintainers
 
 Dr Pen-Yuan Hsing ([@penyuan](https://github.com/penyuan)) is the current maintainer.
@@ -363,6 +353,7 @@ The maintainer would like to gratefully acknowledge:
 * OPENNEXT internal reviewers Dr Jean-François Boujut ([@boujut](https://github.com/boujut)) and Martin Häuer ([@moedn](https://github.com/moedn)) for constructive criticism.
 * OPENNEXT project researchers Robert Mies ([@MIE5R0](https://github.com/MIE5R0)), Mehera Hassan ([@meherrahassan](https://github.com/meherahassan)), and Sonika Gogineni ([@GoSFhg](https://github.com/GoSFhg)) for useful feedback and extensive administrative support.
 * The Linux Foundation [CHAOSS](https://chaoss.community/) group for insights on open source community health metrics.
+* The following people for their valuable feedback via a survey (see D2.5 report for details) (in alphabetical order of last name): Jean-François Boujut ([@boujut](https://github.com/boujut)), Martin Häuer ([@moedn](https://github.com/moedn)), James Jones (CubeSpawn), Max Kampik ([@mkampik](https://github.com/mkampik)), Johannes Střelka-Petz.
 
 [![EU flag](./docs/images/EU_flag.svg)](https://commons.wikimedia.org/wiki/File:Flag_of_Europe.svg)
 
