Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add local contribution guide #69

Open
wants to merge 48 commits into
base: main
Choose a base branch
from
Open
Changes from 1 commit
Commits
Show all changes
48 commits
Select commit Hold shift + click to select a range
3f4c34e
Add draft of local contribution guide
Cli4d Aug 10, 2023
d95cc12
Replace 'repository' with 'collection'
Cli4d Sep 1, 2023
d82d01e
Edit local contrib guide for readability
Cli4d Sep 1, 2023
6a50e95
Improve readability of the local contrib guide
Cli4d Sep 1, 2023
0975c6f
Update contributing-terms.en.md
Cli4d Sep 1, 2023
80c5a55
Update local contrib guide
Cli4d Sep 1, 2023
fffad68
Update content/contributing-terms.en.md
Cli4d Sep 1, 2023
2e67db2
Update content/contributing-terms.en.md
Cli4d Sep 1, 2023
90abc64
Create contributing declarations guide
Cli4d Sep 6, 2023
7a4477e
Create declarations reference page
Cli4d Sep 6, 2023
7834a54
Merge branch 'main' into add-local-contrib-guide
Cli4d Sep 6, 2023
ef117a4
Add draft of local contribution guide
Cli4d Aug 10, 2023
04ef692
Replace 'repository' with 'collection'
Cli4d Sep 1, 2023
5f43358
Edit local contrib guide for readability
Cli4d Sep 1, 2023
d3c2d08
Improve readability of the local contrib guide
Cli4d Sep 1, 2023
2d7b697
Update contributing-terms.en.md
Cli4d Sep 1, 2023
c91b537
Update local contrib guide
Cli4d Sep 1, 2023
9dc38da
Update content/contributing-terms.en.md
Cli4d Sep 1, 2023
6cbf6ae
Update content/contributing-terms.en.md
Cli4d Sep 1, 2023
ede2924
Create contributing declarations guide
Cli4d Sep 6, 2023
4dc051f
Create declarations reference page
Cli4d Sep 6, 2023
0fa611c
Merge branch 'add-local-contrib-guide' of https://github.com/OpenTerm…
Cli4d Sep 6, 2023
96b382b
Fix md linting issues
Cli4d Sep 6, 2023
56de0d7
Fix declarations link
Cli4d Sep 6, 2023
17a2f2c
Merge upstream
MattiSG Oct 3, 2023
eb66ab9
Adds the language to the file name
clementbiron Oct 11, 2023
0fd7310
Fix links
clementbiron Oct 11, 2023
e44267d
Improve code readibility
clementbiron Oct 11, 2023
ea1539a
Merge branch 'main' into add-local-contrib-guide
Cli4d Jan 2, 2024
450dc94
Use inline linking
Cli4d Jan 2, 2024
8dae0fe
Fix typo on repository name
Cli4d Jan 2, 2024
f938ccb
Use contrib tool branch naming
Cli4d Jan 2, 2024
82dae69
Remove Contrib references
Cli4d Jan 2, 2024
6f2dd91
Add service ID link and new terms sect
Cli4d Jan 3, 2024
884ef61
Remove tracking new terms section
Cli4d Jan 3, 2024
b4a900f
Fix md header lint problem
Cli4d Jan 3, 2024
1556b1c
Fix x overflow
clementbiron Jan 10, 2024
86e6a54
Split metadata and governance instructions
MattiSG Dec 19, 2023
eec6d51
Suggest checking known collections when creating
MattiSG Dec 19, 2023
d9dc85b
Suggest to inform the community when creating
MattiSG Dec 19, 2023
008ae78
Add cheesy encouragement to create a collection
MattiSG Dec 19, 2023
60229b7
Add Sponsor role to collection governance
MattiSG Dec 19, 2023
945462c
Define federation assessment criteria means
MattiSG Dec 19, 2023
eba48b4
Define how to join the federation
MattiSG Dec 19, 2023
cfce452
Document supplementary benefits to federation
MattiSG Dec 19, 2023
211c54d
Add draft of local contribution guide
Cli4d Aug 10, 2023
71e8dea
Create contributing declarations guide
Cli4d Sep 6, 2023
3ae5c07
Add draft of local contribution guide
Cli4d Aug 10, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions content/contributing-terms.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -389,6 +389,22 @@ If some parts of the source documents are repeated, they can be factorised. For
```

## Contributing new declarations

This is a step by step guide to help you add declarations to the [contrib-declaration](https://github.com/OpenTermsArchive/contrib-declarations) repository. This repository is dedicated for volunteer contribution of declarations to Open Terms Archive.
Cli4d marked this conversation as resolved.
Show resolved Hide resolved

Having understood briefly how a declaration is structured in JSON format, we need to look at concrete steps on how you can add these JSON files to the repository. To add them, you need to:

1. Clone the [contrib-declaration](https://github.com/OpenTermsArchive/contrib-declarations) repository to your local machine.
Cli4d marked this conversation as resolved.
Show resolved Hide resolved
2. Create a branch that describes your contribution e.g. `add-Open-Terms-Archive-ToS` or `add-firefox-privacy-policy`
Cli4d marked this conversation as resolved.
Show resolved Hide resolved
3. Run `npm install`. This is to install all the dependencies including the Open Terms Archive engine which will allow you to test and validate your declaration to make sure it is ok.
Cli4d marked this conversation as resolved.
Show resolved Hide resolved
Cli4d marked this conversation as resolved.
Show resolved Hide resolved
4. Create a JSON file with the name of the service you are adding the declaration for. This JSON file should be in the `declarations` folder of the repository. To learn more about selecting the right service name, please read the [declaring a new service](#declaring-a-new-service) section of our docs.
Cli4d marked this conversation as resolved.
Show resolved Hide resolved
5. Visit the declaration URL and use [browser developer tools](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Tools_and_setup/What_are_browser_developer_tools) to inspect the page and find the right selectors for the significant section containing the terms you want to declare.
Cli4d marked this conversation as resolved.
Show resolved Hide resolved
6. After you've properly added your selectors and structured your JSON file, you need to test and validate your JSON file to make sure it is ok. To do this, you need to run `npx ota validate --services [service name]` from the root of the repository. This will run a validation on the declaration, highlighting any changes required.
Cli4d marked this conversation as resolved.
Show resolved Hide resolved
7. If all tests are good, make a pull request to the main repository.
Cli4d marked this conversation as resolved.
Show resolved Hide resolved

You can read more about the [CLI](https://docs.opentermsarchive.org/#cli) to learn more about other tests and linting you can run on your declaration
Cli4d marked this conversation as resolved.
Show resolved Hide resolved

#### Terms type

Great, your terms declaration is now almost complete! We simply need to write it under the appropriate terms type in the `documents` JSON object within the service declaration. In order to distinguish between the many terms that can be associated with a service and enable cross-services comparison of similar terms, we maintain a unique list of terms types.
Expand Down
Loading