Merge branch 'wbcsd:main' into nri

wbcsd · Jul 26, 2023 · dd4e495 · dd4e495
2 parents e773aab + ccf7201
commit dd4e495
Show file tree

Hide file tree

Showing 65 changed files with 970 additions and 126 deletions.
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
@@ -1,5 +1,5 @@
 name: validate
-on: [pull_request]
+on: [push, pull_request]
 
 jobs:
   validate:

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,8 @@
+# Change Log
+
+> **_NOTE:_** This file includes all relevant changes to the backend of the [PACT Catalog](https://catalog.carbon-transparency.com). All changes related to the catalog's front end will be listed in the [`pact-catalog-frontend`](https://github.com/sine-fdn/pact-catalog-frontend) repository
+
+**************Changed**************
+
+## 2023-07-20
+Updated the T&Cs as per the latest T&Cs from WBCSD
diff --git a/CONTRIB_EXTENSION.md b/CONTRIB_EXTENSION.md
@@ -8,19 +8,27 @@ To contribute a Data Model Extension, please follow these steps:
 
 From the parent directory of your local repository run
 
+<strong>Please note:</strong> All text between angle brackets (`< >`) should be replaced by actual values. Please make sure that the values replacing `<your-user-id>`, `<extension-id>` only include <strong>lowercase letters and dashes</strong> (instead of whitespace). The value replacing `<extension-version>` should follow the `X.Y.Z` format. Please make sure that these remain consistent. The value replacing `<MIT | CC0>` should be either `"MIT"` or `"CC0"`
+
+
 ```sh
-mkdir -p catalog/data-model-extensions/@<your-name>/<extension-id>/<extension-version>
+mkdir -p catalog/data-model-extensions/@<your-user-id>/<extension-id>/<extension-version>
 ```
 
+E.g., `mkdir -p catalog/data-model-extensions/@abc-institute/example-extension/0.0.0`
+
 ### 2. Populate your extension's directory with the necessary files
 
 From the parent directory of your local repository run
 
 ```sh
-cd catalog/data-model-extensions/@<your-name>/<extension-id>/<extension-version>
+cd catalog/data-model-extensions/@<your-user-id>/<extension-id>/<extension-version>
 touch LICENSE && touch extension.json && touch schema.json && touch README.md
 ```
 
+E.g., `cd catalog/data-model-extensions/abc-institute/example-extension/0.0.0
+touch LICENSE && touch extension.json && touch schema.json && touch README.md`
+
 The `README.md` file is optional, but highly recommended. It should be filled with information about the extension and instructions on how to use it.
 
 ### 3. Fill in your extension's details
@@ -29,33 +37,32 @@ The `README.md` file is optional, but highly recommended. It should be filled wi
 
 Open the `extension.json` file created in step 4. and fill it adapting the following structure:
 
-```json
+```javascript
 {
   "id": {
-    "namespace": "@<your-name>",
-    "extension_name": "<extension-id>",
-    "version": "<extension-version>"
+    "namespace": "@<your-user-id>", // e.g. 'ABC Institute' has user id "abc-institute" or "abc"
+    "extension_name": "<extension-id>", // e.g. "example-extension"
+    "version": "<extension-version>" // e.g. "0.0.0"
   },
-  "name": "<Name of the extension>",
+  "name": "<Name of the extension>", // e.g. "Example Extension"
   "files": ["schema.json"],
   "author": {
-    "name": "<Institution's name>",
+    "name": "<Institution's name>", // e.g. "ABC Institute"
     "email": "<email>",
     "url": "<website>"
   },
-  "license": "<license>",
+  "license": "<MIT | CC0>", // select one
   "catalog_info": {
     "summary": "<Summary of the Extension>",
     "status": "draft",
-    "authors": ["<your-name>"]
+    "authors": ["<your-user-id>"] // same as the one used in the `"namespace"` field (without '@')
   },
   "industries": ["<industry>"]
 }
 ```
 
-Note: the value of `"license"` field must be either `"MIT"` or `"CC0"`.
+Please refer to [this example](./catalog/examples/data-model-extensions/@example-institution/example-extension/0.0.0/extension.json) to see how your `extension.json` should look like.
 
-Please refer to [this example](./catalog/data-model-extensions/@example-institution/example-extension/0.0.0/extension.json) to see how your `extension.json` should look like.
 
 #### 3.2 `schema.json`
 
@@ -69,9 +76,8 @@ You can use [this template](https://github.com/sine-fdn/pact-catalog-frontend/bl
 
 ### 4. Commit your branch, push it, and open a Pull Request
 
-Please continue from [step 4 of the main instructions](/README.md#4-commit-and-push-your-branch).
+Please continue from [step 6 of the main instructions](/README.md#4-commit-and-push-your-branch).
 
-<strong>Please note:</strong> All text between angle brackets (`< >`) should be replaced by actual values. Please make sure that the values replacing `<your-name>`, `<extension-id>` only include <strong>lowercase letters and dashes</strong> (instead of whitespaces). The value replacing `<extension-version>` should follow the `X.Y.Z` format. Please make sure that these remain consistent.
 
 Your Pull Request will be reviewed and added to the PACT Online Catalog as soon as possible.
 

diff --git a/CONTRIB_SOLUTION.md b/CONTRIB_SOLUTION.md
@@ -8,10 +8,14 @@ To contribute a PACT Conformant Solution, please follow these steps:
 
 From the parent directory of your local repository run
 
+<strong>Please note:</strong> All text between angle brackets (`< >`) should be replaced by actual values. Please make sure that the values replacing `<your-user-id>`, `<your-solution-id>` and `<your-solution-version>` only include <strong>lowercase letters and dashes</strong> (instead of whitespace). The value replacing `<your-solution-version>` should follow the `X.Y.Z` format. Please make sure that these remain consistent.
+
 ```sh
 mkdir -p catalog/solutions/<your-solution-id>/<your-solution-version>
 ```
 
+E.g., `mkdir -p catalog/solutions/example-solution/0.0.0`
+
 ### 2. Create a new `json` file in your solution's directory
 
 From the parent directory of your local repository run
@@ -20,40 +24,46 @@ From the parent directory of your local repository run
 touch catalog/solutions/<your-solution-id>/<your-solution-version>/solution.json
 ```
 
+E.g., `touch catalog/solutions/example-solution/0.0.0/solution.json`
+
+
 ### 3. Fill in your solution's details
 
 Open the `json` file created in step 4. and fill it by adapting the following structure:
 
-```json
+
+```javascript
 {
-  "id": "<your-solution-id>",
-  "name": "<your-solution-name>",
-  "version": "<your-solution-version>",
+  "id": "<your-solution-id>", // e.g. 'Example Solution' has solution id "example-solution"
+  "name": "<Your Solution Name>", // e.g. "Example Solution"
+  "version": "<your-solution-version>", // e.g. "0.0.0"
   "website": "<your-solution-website>",
-  "provider": "<your-name>",
+  "provider_id": "<your-user-id>", // e.g. 'ABC Corp' has user id "abc" or "abc-corp"
   "summary": "<summary>"
 }
 ```
 
 Note: The `"summary"` field is optional but highly recommended.
 
-If your solution supports Data Model Extensions, please include also the field `"extensions"`, based on the following structrue:
+If your solution supports Data Model Extensions, please include also the field `"extensions"`, based on the following structure:
 
-```json
+```javascript
   "extensions": [
-    { "namespace": "@<your-name>",
-    "extension_name": "<extension-id>",
-    "version": "<extension-version>" },
+    {
+      "namespace": "@<user-id>", // the id of the user that developed the extension
+      "extension_name": "<extension-id>",
+      "version": "<extension-version>"
+    },
   ],
 ```
 
 If your solution was conceived to be used in specific industries — and especially if it supports Data Model Extensions — please include the field `"industries"`, based on the following structure:
 
-```json
+```javascript
   "industries": ["<industry>"],
 ```
 
-Please refer to [this example](./catalog/solutions/example-solution/0.0.0/solution.json) to see how your `solution.json` file should look like.
+Please refer to [this example](./catalog/examples/solutions/example-solution/0.0.0/solution.json) to see how your `solution.json` file should look like.
 
 ### 4. Contribute a Conformance Test Result
 
@@ -63,9 +73,7 @@ If have already tested your solution for conformance with the Pathfinder Framewo
 
 ### 5. Commit your branch, push it, and open a Pull Request
 
-Please continue from [step 4 of the main instructions](/README.md#4-commit-and-push-your-branch).
-
-<strong>Please note:</strong> All text between angle brackets (`< >`) should be replaced by actual values. Please make sure that the values replacing `<your-name>`, `<your-solution-id>` and `<your-solution-version>` only include <strong>lowercase letters and dashes</strong> (instead of whitespaces). The value replacing `<your-solution-version>` should follow the `X.Y.Z` format. Please make sure that these remain consistent.
+Please continue from [step 6 of the main instructions](/README.md#4-commit-and-push-your-branch).
 
 Your Pull Request will be reviewed and your solution added to the PACT Online Catalog as soon as possible.
 

diff --git a/CONTRIB_TEST.md b/CONTRIB_TEST.md
@@ -8,58 +8,58 @@ To contribute a Conformance Test Result, please follow these steps:
 
 From the parent directory of your local repository run
 
+<strong>Please note:</strong> All text between angle brackets (`< >`) should be replaced by actual values. Please make sure that the values replacing `<your-user-id>`, `<your-solution-id>`, `<your-solution-version>` only include <strong>lowercase letters and dashes</strong> (instead of whitespace). The value replacing `<your-solution-version>` should follow the `X.Y.Z` format. The value replacing `<test-number>` should follow the `XYZ` format, i.e., include three digits from 0 to 9. If this is the first test for a particular solution, please replace it with `001`. Please make sure that these remain consistent.
+
 ```sh
 touch catalog/conformance-tests/result-<your-solution-id>-<test-number>.json
 ```
 
-The `<test-number>` should follow the `XYZ` format. If this is the first test for a particular solution, please replace it with `001`.
+E.g., `touch catalog/conformance-tests/result-example-solution-001.json`
 
 ### 2. Fill in the conformance test details
 
 Open the `json` file created in step 5. and fill it adapting the following structure:
 
-```json
+```javascript
 {
   "tested_solution": {
-    "solution_id": "<your-solution-id>",
-    "version": "<your-solution-version>"
+    "solution_id": "<your-solution-id>", // e.g. 'Example Solution' has solution id "example-solution"
+    "version": "<your-solution-version>" // e.g. "0.0.0"
   },
   "tested_by": {
-    "solution_name": "<solution-name>",
+    "solution_name": "<Solution Name>", // e.g. "Another Solution"
     "version": "<solution-version>",
-    "solution_id": "<solution-id>"
+    "solution_id": "<solution-id>" // e.g. "another-solution"
   },
   "test_result": "passed",
   "test_date": "<date>",
-  "pathfinder_version": "<pathfinder-framework-version>"
+  "pathfinder_version": "<pathfinder-framework-version>" // "1.0.0" or "1.0.1" or "2.0.0" or "2.0.1"
 }
 ```
 
 The `"solution_id"` property of the `"tested_by"` attribute is optional, but highly recommended. All other fields are mandatory.
 
 In case your solution did not pass the test but you nevertheless want to add the conformance test result to the catalog, replace the value of the `"test_result"` field by `"failed"`.
 
-The `<pathfinder-framework-version` can be either `1.0.1` or `2.0.0`.
+The `<pathfinder-framework-version` can be either `1.0.0`, or  `1.0.1` or `2.0.0` or `2.0.1`.
 
 If your solution was tested for specific extensions, please add also the field `"tests"`, based on the following structure:
 
-```json
+```javascript
   "extensions_tested": [
     {
-      "namespace": "@<your-name>",
+      "namespace": "@<user-id>",
       "extension_name": "<extension-id>",
       "version": "<extension-version>"
     }
   ]
 ```
 
-Please refer to [this example](./catalog/conformance-tests/result-example-solution-001.json) to see how your conformance test `json` should look like.
+Please refer to [this example](./catalog/examples/conformance-tests/result-example-solution-001.json) to see how your conformance test `json` should look like.
 
 ### 3. Commit your branch, push it, and open a Pull Request
 
-Please continue from [step 4 of the main instructions](/README.md#4-commit-and-push-your-branch).
-
-<strong>Please note:</strong> All text between angle brackets (`< >`) should be replaced by actual values. Please make sure that the values replacing `<your-name>`, `<your-solution-id>`, `<your-solution-version>` only include <strong>lowercase letters and dashes</strong> (instead of whitespaces). The value replacing `<your-solution-version>` should follow the `X.Y.Z` format. The value replacing `<test-number>` should only include three digits from 0 to 9. Please make sure that these remain consistent.
+Please continue from [step 6 of the main instructions](/README.md#4-commit-and-push-your-branch).
 
 Your Pull Request will be reviewed and your conformance test result added to the PACT Online Catalog as soon as possible.
 

diff --git a/README.md b/README.md
@@ -6,12 +6,14 @@ This repository holds the [PACT Online Catalog](https://pact-catalog.sine.dev).
 
 To contribute to the PACT Online Catalog with an <strong>Data Model Extension</strong>, a <strong>Conformant Solution</strong>, or a <strong>Conformance Test Result</strong>, please follow these steps:
 
-### 1. Fork the `pact-catalog` repository and clone it into your local machine
+### 1. Fork the `pact-catalog` repository
+
+#### 1.1 Fork and clone the `pact-catalog` repository
 
 If you have GitHub CLI tools installed, open a terminal window and run
 
 ```sh
-gh repo fork https://github.com/sine-fdn/pact-catalog.git --clone
+gh repo fork https://github.com/wbcsd/pact-catalog.git --clone
 ```
 
 Otherwise, navigate to the [pact-catalog repository](https://github.com/sine-fdn/pact-catalog.git) and fork it in your browser (instructions can be found [here](https://docs.github.com/en/get-started/quickstart/fork-a-repo#forking-a-repository)).
@@ -22,15 +24,67 @@ Then, open a terminal window and run
 git clone [email protected]:<your-github-id>/pact-catalog.git
 ```
 
-### 2. Checkout a new branch with your institution's name
+#### 1.2 Enable workflows
+
+Go to your forked repository on GitHub, click on the `Actions` tab and then on the green button `I understand my workflows, go ahead and enable them`:
+
+<p align="center">
+  <img src="https://github.com/wbcsd/pact-catalog/assets/100690574/971ec9e4-2222-44d9-ae5c-259d5e4b26f4" width=800>
+</p>
+
+Automatic validation will now run when you commit your branch to GitHub, allowing you to know whether your contribution to the catalog is syntactically correct and minimizing back-and-forth messages and turnover time.
+
+### 2. Checkout a new branch
 
 Run
 
 ```sh
-git checkout -b <your-name>
+git checkout -b <your-branch>
+```
+### 3. Create a new user in the `users` directory
+
+> **_NOTE:_** If you have already created a user, do not create a new one. Instead, please make sure the user you have created is in the `users` directory and that all fields are correct. Then, skip to step 5.
+
+From the parent directory of your local repository run
+
+
+<strong>Please note:</strong> All text between angle brackets (`< >`) should be replaced by actual values. Please make sure that the value replacing `<your-user-id>` only includes <strong>lowercase letters and dashes</strong> (instead of whitespace). The value replacing `<solutionprovider | ngo | company>` should be `"solutionprovider"`, `"ngo"`, or `"company"`, depending on your situation.
+
+```sh
+touch catalog/users/<your-user-id>.json
+```
+
+E.g., `touch catalog/users/abc-corp.json`
+
+### 4. Fill in your user's details
+
+Open the `json` file created in step 4. and fill it by adapting the following structure:
+
+```javascript
+{
+  "id": "<your-user-id>", // e.g. 'ABC Corp' has user id "abc" or "abc-corp"
+  "kind": "<solutionprovider | ngo | company>", // select one
+  "name": "<Your Name>", // e.g. "ABC Corp"
+  "email": "<your-email>",
+  "website": "<your-website>",
+  "logo": "<url-to-your-logo>" // to be displayed in the collaborators page (optional)
+}
 ```
 
-### 3. Follow the contribution-specific tests
+If you already endorse Data Model Extensions, please include also the field `"extensions_endorsed"`, based on the following structure:
+```javascript
+ "extensions_endorsed": [
+    {
+      "namespace": "@<user-id>", // the id of the user that developed the extension
+      "extension_name": "<extension-id>",
+      "version": "<extension-version>"
+    }
+  ]
+```
+
+Please refer to [this example](./catalog/examples/users/example-institution.json) to see how your `<your-user-id>.json` file should look like.
+
+### 5. Follow the contribution-specific tests
 
 If you want to contribute an <strong>Data Model Extension</strong>, please follow [these steps](/CONTRIB_EXTENSION.md).
 
@@ -40,24 +94,24 @@ If you want to contribute a <strong>Conformance Test Result</strong>, please fol
 
 Once you have done that, please proceed to the next step.
 
-### 4. Commit and push your branch
+### 6. Commit and push your branch
 
 From the parent directory of the repository, run
 
 ```sh
 git add .
 git commit -m "feat: <commit-message>"
-git push origin <your-name>
+git push origin <yourbranch>
 ```
 
 Please replace `<commit-message>` with a short description, such as `add <extension-id> extension`, `add <your-solution-id> solution`, or `add <tested-solution-id> test result`.
 
-## 5. Open a Pull Request
+### 7. Open a Pull Request
 
 Go to the original [pact-catalog repository](https://github.com/sine-fdn/pact-catalog), choose the `Pull requests` tab and click the `New pull request` button.
-Open a Pull Request to merge the branch `<your-name>` from your forked repository into the `main` branch of the `pact-catalog` repository. Instructions on how to open Pull Requests across forks can be found [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
+Open a Pull Request to merge the branch `<your-user-id>` from your forked repository into the `main` branch of the `pact-catalog` repository. Instructions on how to open Pull Requests across forks can be found [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
 
-<strong>Please note:</strong> All text between angle brackets (`< >`) should be replaced by actual values. Please make sure that the values replacing `<your-name>`, `<extenion-id>`, `<extension-version>`,`<your-solution-id>` only include <strong>lowercase letters and dashes</strong> (instead of whitespaces). The values replacing `<extension-version>` and `<your-solution-version>` should follow the `X.Y.Z` format. Please make sure that these remain consistent.
+<strong>Please note:</strong> All text between angle brackets (`< >`) should be replaced by actual values. Please make sure that the values replacing `<your-user-id>`, `<extenion-id>`, `<extension-version>`,`<your-solution-id>` only include <strong>lowercase letters and dashes</strong> (instead of whitespaces). The values replacing `<extension-version>` and `<your-solution-version>` should follow the `X.Y.Z` format. Please make sure that these remain consistent.
 
 Your Pull Request will be reviewed and your solution added to the PACT Online Catalog as soon as possible.
 

diff --git a/catalog/conformance-tests/result-atma-io-001.json b/catalog/conformance-tests/result-atma-io-001.json
@@ -0,0 +1,15 @@
+{
+  "tested_solution": {
+    "solution_id": "atma-io",
+    "version": "2.0.1"
+  },
+   "tested_by": {
+    "solution_name": "TrueCarbon",
+    "version": "2.0.0",
+    "solution_id": "cirrus-nexus-true-carbon-for-pact-01"
+  },
+  "test_result": "passed",
+  "test_date": "2023-06-28T00:00:00Z",
+  "pathfinder_version": "2.0.0",
+  "extensions_tested": []
+}