Skip to content

[prototype] Interactively declare services to be tracked in Open Terms Archive

License

Notifications You must be signed in to change notification settings

alessandrozago/contribution-tool

This branch is 5 commits behind OpenTermsArchive/contribution-tool:main.

Folders and files

NameName
Last commit message
Last commit date
Nov 19, 2024
Nov 12, 2024
Oct 18, 2023
Nov 19, 2024
Nov 1, 2022
Nov 21, 2024
Nov 21, 2024
Mar 8, 2022
Jan 13, 2022
Jan 13, 2022
Nov 21, 2024
Nov 15, 2024
Jul 18, 2022
Jul 21, 2022
Sep 28, 2022
Nov 15, 2022
Mar 8, 2022
Nov 15, 2022
Nov 15, 2024
Nov 19, 2024
Jan 13, 2022
Jun 29, 2022
Mar 24, 2022

Repository files navigation

Open Terms Archive Contribution Tool Prototype

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.

Status

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.

Introduction

Build on Next.js react framework, using TypeScript and PostCSS.

Configuration

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

Port on which the website will run.

Example PORT=5000 Default is 3000

NEXT_PUBLIC_BASE_PATH

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

GITHUB_TOKEN

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.

GITLAB_TOKEN

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.

GITLAB_TOKEN_VERSIONS

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.

GITLAB_URL

In order for the service to use the GitLab APIs to interact with the repositories, you need the below environment variables:

GITLAB_PROJECT_ID

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.

NEXT_PUBLIC_MATOMO_URL, NEXT_PUBLIC_MATOMO_SITE_ID

You can easily set up analytics with Matomo by providing those 2 values.

Contribution interface Usage

Destination repository (Mandatory)

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)

Usage

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.

Local creation of services from contribution interface

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.

Automatically generating history file

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.

Contributing

See our contributing guide.

License

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.

About

[prototype] Interactively declare services to be tracked in Open Terms Archive

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • CSS 48.0%
  • JavaScript 30.2%
  • TypeScript 21.0%
  • Other 0.8%