This is the repository for contribute.opentermsarchive.org, the proof of concept of a tool that helps users create declarations for Open Terms Archive collections.
This codebase is untested and should be considered as a proof of concept only, usable by trained contributors for specific cases where reliability is not critical. It is not safe to deploy in production.
Build on Next.js react framework, using TypeScript and PostCSS.
Copy .env.example to .env file at the root of the project and fill in the values of the constants.
Note that you can use Nextjs Documentation if you wish to add more environment variables
Port on which the website will run.
Example PORT=5000
Default is 3000
To deploy the website under a sub-path of a domain you can use this env variable config option.
Example NEXT_PUBLIC_BASE_PATH="/prefix"
Default is empty
In order for the service to automatically create issues in Github when a submitting a new service declaration, you need the below environment variables:
GITHUB_TOKEN: A token with repository privileges which allow access to the GitHub API.
In order for the service to automatically create issues in GitLab when a submitting a new service declaration, you need the below environment variables:
GITLAB_TOKEN: A token with the api scope which allows access to the GitLab API.
In order for the service to read from the versions repository in GitLab to edit a commit, you need the below environment variables:
GITLAB_TOKEN_VERSIONS: A token with the read_api scope which allows read access to the GitLab API.
In order for the service to use the GitLab APIs to interact with the repositories, you need the below environment variables:
GITLAB_URL: The base api url of the GitLab server (for example it would be https://gitlab.com/api/v4/ if hosted on gitlab.com).
In order for the service to use the GitLab APIs to interact with the declarations repository, you need the below environment variables:
GITLAB_PROJECT_ID: The project ID of the repository.
You can easily set up analytics with Matomo by providing those 2 values.
The contribution interface can be used against any repository on which github user which generated the GITHUB_TOKEN has issue creation rights.
This repo must be passed by an url parameter called destination
Here are some examples for contributing to different projects using
- /en?destination=OpenTermsArchive/contrib-declarations
- /en?destination=OpenTermsArchive/dating-declarations
- /en?destination=OpenTermsArchive/sandbox (For tests)
Once destination is setup, you need to enter an url and follow the written guidelines.
After selecting the page parts you want to track, clicking on Validate will automatically create an issue in the given destination github repository.
In case this automatic creation does not work, a fallback is setup, opening a mailto link with prepopulated data.
If you are interested in setting up a local instance where you can locally save the result of the contribution interface, you have to specify where to save it.
This can be done with a url parameter called localPath.
It takes a full local path string and must point to the exact folder containing the declarations. See below examples:
/en?destination=OpenTermsArchive/contrib-declarations&localPath=/Users/username/Workspace/OpenTermsArchive/contrib-declarations/declarations
/en?destination=OpenTermsArchive/dating-declarations&localPath=/Users/username/Workspace/somewhere-else/dating-declarations/declarations
This way, a Save on local button will appear on the contribution interface. By clicking on it, it will add or modify the service declaration (saved as a .json file) in the corresponding directory.
As we want to ensure we can retrace the whole history of selectors we used to retrieve the corresponding documents, a history file should be created every time you change the service declaration (See the corresponding decision record. As this is a very time consuming thing to do (retrieve the last version date, format it in ISO format and pasting it in a history file), an attempt to find this date has been implemented. When having the Local creation of services from contribution interface feature enabled, if a service file already exists, the contribution tool will try to retrieve the first error referenced on GitHub concerning this document, will fetch its date and add the record to the history file. This will not always be accurate but we'll use this until the core of Open Terms Archive provides such a feature.
See our contributing guide.
The code for this software is distributed under the European Union Public Licence (EUPL) v1.2. Contact the author if you have any specific need or question regarding licensing.