doc: add adrs

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "adr.project.directory": "doc/adr",
+  "adr.templates.directory": ".adr-templates",
+  "adr.templates.repo": "https://github.com/vincent-ledu/adr-template.git"
+}

README.md

@@ -13,6 +13,7 @@ It defines a data model that can be used to build an inventory of the tools.
 - [🗺️ Mapping of the ICT Sustainability Tools Landscape](#️-mapping-of-the-ict-sustainability-tools-landscape)
   - [Repository content](#repository-content)
   - [Implementation](#implementation)
+    - [Architecture decisions records / ADRs](#architecture-decisions-records--adrs)
     - [General design](#general-design)
       - [Usage flow](#usage-flow)
       - [Components](#components)
@@ -33,20 +34,24 @@ It defines a data model that can be used to build an inventory of the tools.
 
 ## Implementation
 
+### Architecture decisions records / ADRs
+
+- [ADR list](doc/adr/flowChart.md)
+- [All ADRs](doc/adr/)
+
 ### General design
 
 We use a [Datami](https://datami-docs.multi.coop/?locale=en) widget to display data and allow edition of a file stored in Github. Even if end user is not familiar with Git.
 
 1. data is stored in GIT to benefit from historisation, review and approval workflows (and potential automatic validation of format)
 2. data update can be proposed by end users in 2 ways:
-   1.  A web frontend that allow to view the data and propose edition => This is the **preferred** solution using Datami widget
+   1. A web frontend that allow to view the data and propose edition => This is the **preferred** solution using Datami widget
    2. Pull requests directly against the data file (git) => **Less preferred** (mainly for maintainers of people familiar with Git)
 
 #### Usage flow
 
 ![usage flow](doc/usage-flow.excalidraw.png)
 
-
 #### Components
 
 ![Components of datami widget](doc/datami-components.excalidraw.png)
@@ -68,8 +73,8 @@ We use a [Datami](https://datami-docs.multi.coop/?locale=en) widget to display d
 
 See [draft dataset](old-examples/ict-sustainability-tools.csv)
 
-
 ### Example Datami widgets
 
 - A CSV file displayed without any customization [old-examples/csv/csv-widget-basic.html](old-examples/csv/csv-widget-basic.html)
 - A CSV file displayed with some additional constraints on fields [old-examples/csv/csv-widget-with-constraints.html](old-examples/csv/csv-widget-with-constraints.html).
+- Other examples with more complex validation rules:[GitHub - demeringo/datami-tests: Testing datami widget to edit and validate csv files](https://github.com/demeringo/datami-tests/)

doc/adr/.adr-persist.json

@@ -0,0 +1 @@
+{"nodes":[{"index":"0000","filename":"0000-record-architecture-decisions.md","title":"Record architecture decisions","statuses":[{"date":"1716336000000","status":"Accepted"}]},{"index":"0001","filename":"0001-dataset-should-be-public-to-allow-review.md","title":"Dataset should be public to allow review","statuses":[{"date":"1716336000000","status":"Accepted"}]},{"index":"0002","filename":"0002-use-csv-as-data-format.md","title":"Use CSV as data format","statuses":[{"date":"1716336000000","status":"Accepted"}]},{"index":"0003","filename":"0003-use-datami-to-ease-visualization-or-edition-of-data.md","title":"Use Datami to ease visualization or edition of data","statuses":[{"date":"1716336000000","status":"Accepted"}]}],"links":[]}

doc/adr/0000-record-architecture-decisions.md

@@ -0,0 +1,21 @@
+# 0. Record architecture decisions
+
+Date: 2024-05-22
+
+## Status
+
+Status: Accepted on 2024-05-22
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Consequences
+
+See Michael Nygard's article, linked above. 
+For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).
+For a Visual Studio Code ADR toolset extention, see Vincent Le Dû's [vscode-adr-extention](https://github.com/vincent-ledu/adr-template)

doc/adr/0001-dataset-should-be-public-to-allow-review.md

@@ -0,0 +1,22 @@
+# 1. Dataset should be public to allow review
+
+Date: 2024-05-22
+
+## Status
+
+Status: Accepted on 2024-05-22  
+
+## Context
+
+We want the dataset to be reviewable by external contributors.
+
+## Decision
+
+The dataset is hosted on a publicly accessible GitHub.
+
+## Consequences
+
+- We can benefit from standard git contribution process (Pull Request)
+- We benefit from traceability and historisation of changes.
+- Needs to formalize a contribution and review process.
+- Not everybody is fluent in using GitHub.

doc/adr/0002-use-csv-as-data-format.md

@@ -0,0 +1,21 @@
+# 2. Use CSV as data format
+
+Date: 2024-05-22
+
+## Status
+
+Status: Accepted on 2024-05-22  
+
+
+## Context
+
+We want the data set to be easily editable, with minimal tooling or account creation.
+
+## Decision
+
+We use CSV as the data format.
+
+## Consequences
+
+- The model/data dictionary of this CSV file needs to be carefully described and this documentation has to be public.
+- CSV does not provides direct way to reference a schema, we need to use a external mechanism to ensure its consistency.

doc/adr/0003-use-datami-to-ease-visualization-or-edition-of-data.md

@@ -0,0 +1,28 @@
+# 3. Use Datami to ease visualization or edition of data
+
+Date: 2024-05-22
+
+## Status
+
+Status: Accepted on 2024-05-22  
+
+
+## Context
+
+The data is stored as CSV on GitHub but most users or contributors of the data may not be very familiar Github.
+
+- We still want theses non-technical users to be able to visualize or edit (propose changes) on the data.
+- We want to benefit from traceability and historisation of changes (Pull requests).
+- We do want to maintain accounts or access rights on a specific system to allow to submit a update on data.
+- We want to limit as much as possible the load on Boavizta benevolent members for the submission review process.
+
+## Decision
+
+We use Datami [https://datami-docs.multi.coop/?locale=en](https://datami-docs.multi.coop/?locale=en), an open source widget that allows users to visualize or contribute to data.
+
+## Consequences
+
+- Contributors or users do not need specific access rights to view/edit data.
+- Need to customize configuration of widget to our needs (display and constraints on edition).
+- Need to define a shared Github token to allow contribution from the widget.
+- Need to choose where we will host the the public page that includes the widget.

doc/adr/flowChart.md

@@ -0,0 +1,11 @@
+```mermaid
+graph LR
+0000[Record architecture decisions]
+click 0000 "0000-record-architecture-decisions.md"
+0001[Dataset should be public to allow review]
+click 0001 "0001-dataset-should-be-public-to-allow-review.md"
+0002[Use CSV as data format]
+click 0002 "0002-use-csv-as-data-format.md"
+0003[Use Datami to ease visualization or edition of data]
+click 0003 "0003-use-datami-to-ease-visualization-or-edition-of-data.md"
+```