From 9ec1ac03d171765adaaeb1b359d2a19311ed2838 Mon Sep 17 00:00:00 2001 From: clementbiron Date: Tue, 11 Jun 2024 08:08:21 +0000 Subject: [PATCH] deploy: 4459f021db0d998eda4b72754f307d37b1278561 --- api/collection/index.html | 2 +- api/federation/index.html | 2 +- api/node/index.html | 2 +- collections/create/index.html | 2 +- collections/federation/index.html | 2 +- collections/governance/index.html | 2 +- collections/metadata/index.html | 2 +- contributing-terms/index.html | 2 +- design-principles/index.html | 2 +- en/sitemap.xml | 2 +- guidelines/choosing-selectors/index.html | 2 +- guidelines/declaring/index.html | 2 +- guidelines/reviewing/index.html | 2 +- guidelines/targeting/index.html | 2 +- index.html | 2 +- index.xml | 11 +++++++---- jsdoc/Record.html | 2 +- jsdoc/archivist_extract_index.js.html | 2 +- jsdoc/archivist_fetcher_index.js.html | 2 +- jsdoc/archivist_recorder_record.js.html | 2 +- .../archivist_recorder_repositories_interface.js.html | 2 +- jsdoc/collection-api_routes_services.js.html | 2 +- jsdoc/collection-api_routes_versions.js.html | 2 +- jsdoc/global.html | 2 +- jsdoc/index.html | 2 +- memos/copywriting-reference/index.html | 7 +++++++ memos/how-to-publish/index.html | 7 +++++++ memos/index.xml | 7 +++++-- memos/writing-reference/index.html | 7 ------- navigate-history/index.html | 2 +- subscribe-rss/index.html | 2 +- 31 files changed, 52 insertions(+), 39 deletions(-) create mode 100644 memos/copywriting-reference/index.html create mode 100644 memos/how-to-publish/index.html delete mode 100644 memos/writing-reference/index.html diff --git a/api/collection/index.html b/api/collection/index.html index d299c88..e2e48c3 100644 --- a/api/collection/index.html +++ b/api/collection/index.html @@ -2,6 +2,6 @@ EN
FR

Collection Web API [Beta]

As Open Terms Archive is decentralised, each instance embarks its own API. The documentation relevant to the specific version of the engine on that instance is provided on that instance itself.

The Collection API exposes JSON data over HTTP. Its OpenAPI specification can be found at http://localhost:<port>/<basePath>/<API version>/docs.

That endpoint exposes both the OpenAPI specification if the requested Content-Type is JSON, and a Swagger UI for visual and interactive documentation otherwise.

For example, the documentation of the Demo collection is publicly available for exploration.

+Close

Collection Web API [Beta]

As Open Terms Archive is decentralised, each instance embarks its own API. The documentation relevant to the specific version of the engine on that instance is provided on that instance itself.

The Collection API exposes JSON data over HTTP. Its OpenAPI specification can be found at http://localhost:<port>/<basePath>/<API version>/docs.

That endpoint exposes both the OpenAPI specification if the requested Content-Type is JSON, and a Swagger UI for visual and interactive documentation otherwise.

For example, the documentation of the Demo collection is publicly available for exploration.

\ No newline at end of file diff --git a/api/federation/index.html b/api/federation/index.html index ee65e24..9cc8c04 100644 --- a/api/federation/index.html +++ b/api/federation/index.html @@ -2,7 +2,7 @@ EN
FR

Federation API

Open Terms Archive is a decentralised system that tracks collections of services’ terms across multiple servers. Each collection operates its own API, and the Federation API unifies search and discovery across collections, fostering collaboration with external applications.

The Federation API exposes JSON data over HTTP. Its documentation is provided in a dedicated, interactive interface.

That endpoint exposes both the OpenAPI specification if the requested Content-Type is JSON, and a Swagger UI for visual and interactive documentation otherwise.

Beta

This API is offered as a preview, based on a first use case defined with partner ToS;DR. Unexpected problems or missing functionality may arise. Please provide feedback through issues in the dedicated repository.

Source code

The codebase for the Federation API is available on github.com/OpenTermsArchive/federation-api.

Configuring

The default configuration can be found in config/default.json. The full reference is given below. In the vast majority of cases, the default values should be sufficient and only the email sending data should be changed.

{
+Close

Federation API

Open Terms Archive is a decentralised system that tracks collections of services’ terms across multiple servers. Each collection operates its own API, and the Federation API unifies search and discovery across collections, fostering collaboration with external applications.

The Federation API exposes JSON data over HTTP. Its documentation is provided in a dedicated, interactive interface.

That endpoint exposes both the OpenAPI specification if the requested Content-Type is JSON, and a Swagger UI for visual and interactive documentation otherwise.

Beta

This API is offered as a preview, based on a first use case defined with partner ToS;DR. Unexpected problems or missing functionality may arise. Please provide feedback through issues in the dedicated repository.

Source code

The codebase for the Federation API is available on github.com/OpenTermsArchive/federation-api.

Configuring

The default configuration can be found in config/default.json. The full reference is given below. In the vast majority of cases, the default values should be sufficient and only the email sending data should be changed.

{
   "@opentermsarchive/federation-api": {
     "logger": { // Logging mechanism to be notified upon error
       "smtp": {
diff --git a/api/node/index.html b/api/node/index.html
index 3e47560..c3729b7 100644
--- a/api/node/index.html
+++ b/api/node/index.html
@@ -2,7 +2,7 @@
 EN
FR

Node.js API [Beta]

As a Node module dependency, the engine exposes a JavaScript API that can be called in your own code. The following modules are available.

fetch

The fetch module gets the MIME type and content of a document from its URL

import fetch from '@opentermsarchive/engine/fetch';
+Close

Node.js API [Beta]

As a Node module dependency, the engine exposes a JavaScript API that can be called in your own code. The following modules are available.

fetch

The fetch module gets the MIME type and content of a document from its URL

import fetch from '@opentermsarchive/engine/fetch';

Documentation on how to use fetch is provided as JSDoc.

Headless browser management

If you pass the executeClientScripts option to fetch, a headless browser will be used to download and execute the page before serialising its DOM. For performance reasons, the starting and stopping of the browser is your responsibility to avoid instantiating a browser on each fetch. Here is an example on how to use this feature:

import fetch, { launchHeadlessBrowser, stopHeadlessBrowser } from '@opentermsarchive/engine/fetch';
 
 await launchHeadlessBrowser();
diff --git a/collections/create/index.html b/collections/create/index.html
index b30b648..24b376f 100644
--- a/collections/create/index.html
+++ b/collections/create/index.html
@@ -2,7 +2,7 @@
 EN
FR

Creating a collection

You are considering creating a new collection to track terms with Open Terms Archive? Amazing!

Define metadata

First of all, define the metadata of the collection you would like to create.

Check existing collections

Now that you have a clear idea what you would like to track, double-check that there are no existing federated collections that you could contribute to. If you have a doubt about whether some terms you want to track would fit a collection, reach out to the collection maintainers.

If no existing collection could be a good host for the terms you would like to track, then it is relevant to create your own.

Inform the community

Starting a new collection is an exciting endeavour, and would strongly benefit from the support of the community who already maintains existing collections. It is strongly recommended to share your intention to create a new collection as early as possible in the process, to get support and identify potential partners.

You can inform the community by posting on the instant messaging system, or sending an email to the core team.

Define governance

Setting up and maintaining a collection over time needs fulfilling certain tasks on a regular basis. These tasks are handled through roles. To make sure that all these roles are covered, define the governance of your collection.

At any time, feel free to ask for help or partners in the community.

Create repositories

Collections rely on three git repositories being set up to hold the data.

The instructions below assume the usage of GitHub to host repositories. If you don’t use GitHub, try to set up the equivalent metadata in your git hosting platform. Contributions to the documentation to make it independent from GitHub are very welcome!

Declarations

Create the collection declarations repository by using the demo-declarations repository as template.

  • Go to the demo-declarations repository
  • Click on the “Use this template” dropdown and select “Create a new repository”
  • Set the repository name to <collection_id>-declarations. For example: pga-declarations.
  • When redirected to the newly generated repository, wait a minute or two for the automatic setup to run. You can check the status of the first-time-setup GitHub action to make sure that everything ran fine.

Fill the “About” section

  • Click on the little cogwheel icon next to the “About” block.
  • Set the description to “Declarations for <collection_name>. Maintained by <maintainer>.”
  • Set website to https://opentermsarchive.org, or any other relevant dedicated website.
  • Add the following tags: terms-of-service, terms-of-service-agreements, terms-and-conditions, open-terms-archive.
  • Uncheck “Releases”, “Packages” and “Deployments”.

Define repository settings

These settings ease the whole contribution process.

  • In “General → Features”
    • Disable “Wikis”.
    • Disable “Projects”.
  • In “General → Pull Requests”
    • Check only the “Allow squash merging” option, and set it to “Default to pull request title and commit details”.
    • Enable “Allow auto-merge”.
    • Enable “Automatically delete head branches”.
  • In “Branches”
    • Add a branch protection rule for main.
      • Check “Require a pull request before merging”, check “Require approvals” and set “Required number of approvals before merging” to 1.
      • Check “Require status checks to pass before merging” and add validate_modified_declarations and validate_schema as required status checks.
  • In “Actions → General → Actions permissions”
    • Select “Allow all actions and reusable workflows”.

Remove default labels

Issues labels will be added by the engine as problems are encountered when tracking. The default labels offered by GitHub, such as question or wontfix, are relevant for software development but less so for the process prescribed by Open Terms Archive.

  • Remove all default labels.

Update README

  • Update the README file with proper metadata: topic, maintainers, jurisdictions, languages…

Snapshots

Create the snapshots repository by using the demo-snapshots repository as template:

  • Go to the demo-snapshots repository
  • Click on the “Use this template” dropdown and select “Create a new repository”
  • Set the repository name to <collection_id>-snapshots.
  • When redirected to the newly generated repository, wait a minute or two for the automatic setup to run. You can check the status of the first-time-setup GitHub action to make sure that everything ran fine.

Fill the “About” section

  • Set the description: “Documents snapshots for <collection_name>. Maintained by <maintainer>.”
  • Set website to https://opentermsarchive.org.
  • Add the following tags: terms-of-service, terms-of-service-agreements, terms-and-conditions, open-terms-archive.
  • Uncheck “Releases”, “Packages” and “Deployments”.

Define repository settings

These settings aim at minimising the otherwise overwhelming amount of information and click targets.

  • In “General → Features”
    • Uncheck “Wikis”.
    • Uncheck “Issues”.
    • Uncheck “Discussions”.
    • Uncheck “Projects”.
  • In “Actions → General → Actions permissions”
    • Select “Disable actions”.

Versions

Create the versions repository by using the demo-versions repository as template:

  • Go to the demo-versions repository
  • Click on the “Use this template” dropdown and select “Create a new repository”
  • Set the repository name to <collection_id>-versions.
  • When redirected to the newly generated repository, wait a minute or two for the automatic setup to run. You can check the status of the first-time-setup GitHub action to make sure that everything ran fine.

Fill the “About” section

  • Set the description: “Terms versions for <collection_name>. Maintained by <maintainer>.”
  • Set website to https://docs.opentermsarchive.org/navigate-history/
  • Add the following tags: terms-of-service, terms-of-service-agreements, terms-and-conditions, open-terms-archive.
  • Uncheck “Packages”.
  • Uncheck “Deployments”.

Define repository settings

These settings aim at minimising the otherwise overwhelming amount of information and click targets.

  • In “General → Features”
    • Uncheck “Wikis”.
    • Uncheck “Issues”.
    • Uncheck “Discussions”.
    • Uncheck “Projects”.
  • In “Actions → General → Actions permissions”
    • Select “Disable actions”.

Update README

  • Update the README file with proper metadata.

Set up GitHub teams

For collections to be included in the Open Terms Archive organisation only. For third parties, handle rights however you see fit.

  • Create a new collection team
  • Give it the name of the collection
  • Set as avatar the collection icon from the website
  • Set as description: “Maintainers of the <collection_name> collection”
  • Add selected members to the team
  • Add the declarations repository to the collection team, with “Maintain” access rights
  • Add the snapshots repository to the collection team, with “Triage” access rights (giving them more would enable them to corrupt data)
  • Add the versions repository to the collection team, with “Triage” access rights (giving them more would enable them to corrupt data)
  • Add the declarations, snapshots and versions repositories to the Bots team with “Write” access

Set up deployment

Check server configuration

Before proceeding with deployment, ensure that the server meets the following requirements:

  • Verify that the server provides an Ed25519 fingerprint for its SSH host key:

    • Retrieve the Ed25519 SSH host key from the server ssh-keyscan -t ed25519 <server_address>
    • If the server has an Ed25519 SSH host key defined, the output will display the corresponding fingerprint. It will look something like this:
      <server_address> ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJM6fCKWkiKv+uysoHsklIAuUOH6Dpc3crzHxk7GwrD
+Close

Creating a collection

You are considering creating a new collection to track terms with Open Terms Archive? Amazing!

Define metadata

First of all, define the metadata of the collection you would like to create.

Check existing collections

Now that you have a clear idea what you would like to track, double-check that there are no existing federated collections that you could contribute to. If you have a doubt about whether some terms you want to track would fit a collection, reach out to the collection maintainers.

If no existing collection could be a good host for the terms you would like to track, then it is relevant to create your own.

Inform the community

Starting a new collection is an exciting endeavour, and would strongly benefit from the support of the community who already maintains existing collections. It is strongly recommended to share your intention to create a new collection as early as possible in the process, to get support and identify potential partners.

You can inform the community by posting on the instant messaging system, or sending an email to the core team.

Define governance

Setting up and maintaining a collection over time needs fulfilling certain tasks on a regular basis. These tasks are handled through roles. To make sure that all these roles are covered, define the governance of your collection.

At any time, feel free to ask for help or partners in the community.

Create repositories

Collections rely on three git repositories being set up to hold the data.

The instructions below assume the usage of GitHub to host repositories. If you don’t use GitHub, try to set up the equivalent metadata in your git hosting platform. Contributions to the documentation to make it independent from GitHub are very welcome!

Declarations

Create the collection declarations repository by using the demo-declarations repository as template.

  • Go to the demo-declarations repository
  • Click on the “Use this template” dropdown and select “Create a new repository”
  • Set the repository name to <collection_id>-declarations. For example: pga-declarations.
  • When redirected to the newly generated repository, wait a minute or two for the automatic setup to run. You can check the status of the first-time-setup GitHub action to make sure that everything ran fine.

Fill the “About” section

  • Click on the little cogwheel icon next to the “About” block.
  • Set the description to “Declarations for <collection_name>. Maintained by <maintainer>.”
  • Set website to https://opentermsarchive.org, or any other relevant dedicated website.
  • Add the following tags: terms-of-service, terms-of-service-agreements, terms-and-conditions, open-terms-archive.
  • Uncheck “Releases”, “Packages” and “Deployments”.

Define repository settings

These settings ease the whole contribution process.

  • In “General → Features”
    • Disable “Wikis”.
    • Disable “Projects”.
  • In “General → Pull Requests”
    • Check only the “Allow squash merging” option, and set it to “Default to pull request title and commit details”.
    • Enable “Allow auto-merge”.
    • Enable “Automatically delete head branches”.
  • In “Branches”
    • Add a branch protection rule for main.
      • Check “Require a pull request before merging”, check “Require approvals” and set “Required number of approvals before merging” to 1.
      • Check “Require status checks to pass before merging” and add validate_modified_declarations and validate_schema as required status checks.
  • In “Actions → General → Actions permissions”
    • Select “Allow all actions and reusable workflows”.

Remove default labels

Issues labels will be added by the engine as problems are encountered when tracking. The default labels offered by GitHub, such as question or wontfix, are relevant for software development but less so for the process prescribed by Open Terms Archive.

  • Remove all default labels.

Update README

  • Update the README file with proper metadata: topic, maintainers, jurisdictions, languages…

Snapshots

Create the snapshots repository by using the demo-snapshots repository as template:

  • Go to the demo-snapshots repository
  • Click on the “Use this template” dropdown and select “Create a new repository”
  • Set the repository name to <collection_id>-snapshots.
  • When redirected to the newly generated repository, wait a minute or two for the automatic setup to run. You can check the status of the first-time-setup GitHub action to make sure that everything ran fine.

Fill the “About” section

  • Set the description: “Documents snapshots for <collection_name>. Maintained by <maintainer>.”
  • Set website to https://opentermsarchive.org.
  • Add the following tags: terms-of-service, terms-of-service-agreements, terms-and-conditions, open-terms-archive.
  • Uncheck “Releases”, “Packages” and “Deployments”.

Define repository settings

These settings aim at minimising the otherwise overwhelming amount of information and click targets.

  • In “General → Features”
    • Uncheck “Wikis”.
    • Uncheck “Issues”.
    • Uncheck “Discussions”.
    • Uncheck “Projects”.
  • In “Actions → General → Actions permissions”
    • Select “Disable actions”.

Versions

Create the versions repository by using the demo-versions repository as template:

  • Go to the demo-versions repository
  • Click on the “Use this template” dropdown and select “Create a new repository”
  • Set the repository name to <collection_id>-versions.
  • When redirected to the newly generated repository, wait a minute or two for the automatic setup to run. You can check the status of the first-time-setup GitHub action to make sure that everything ran fine.

Fill the “About” section

  • Set the description: “Terms versions for <collection_name>. Maintained by <maintainer>.”
  • Set website to https://docs.opentermsarchive.org/navigate-history/
  • Add the following tags: terms-of-service, terms-of-service-agreements, terms-and-conditions, open-terms-archive.
  • Uncheck “Packages”.
  • Uncheck “Deployments”.

Define repository settings

These settings aim at minimising the otherwise overwhelming amount of information and click targets.

  • In “General → Features”
    • Uncheck “Wikis”.
    • Uncheck “Issues”.
    • Uncheck “Discussions”.
    • Uncheck “Projects”.
  • In “Actions → General → Actions permissions”
    • Select “Disable actions”.

Update README

  • Update the README file with proper metadata.

Set up GitHub teams

For collections to be included in the Open Terms Archive organisation only. For third parties, handle rights however you see fit.

  • Create a new collection team
  • Give it the name of the collection
  • Set as avatar the collection icon from the website
  • Set as description: “Maintainers of the <collection_name> collection”
  • Add selected members to the team
  • Add the declarations repository to the collection team, with “Maintain” access rights
  • Add the snapshots repository to the collection team, with “Triage” access rights (giving them more would enable them to corrupt data)
  • Add the versions repository to the collection team, with “Triage” access rights (giving them more would enable them to corrupt data)
  • Add the declarations, snapshots and versions repositories to the Bots team with “Write” access

Set up deployment

Check server configuration

Before proceeding with deployment, ensure that the server meets the following requirements:

  • Verify that the server provides an Ed25519 fingerprint for its SSH host key:

    • Retrieve the Ed25519 SSH host key from the server ssh-keyscan -t ed25519 <server_address>
    • If the server has an Ed25519 SSH host key defined, the output will display the corresponding fingerprint. It will look something like this:
      <server_address> ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJM6fCKWkiKv+uysoHsklIAuUOH6Dpc3crzHxk7GwrD
    • If no output is displayed or if the output does not include an Ed25519 SSH host key fingerprint, it indicates that the server does not have an Ed25519 SSH host key defined. Here’s an example of the output when no Ed25519 SSH host key is defined:
      # <server_address> SSH-2.0-OpenSSH_8.2p1 Ubuntu-4ubuntu0.3
   <server_address> ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDqruXk1P6vIVvN2i6ffLO6TlYCcC6lqF3oBYT7sC+nfIb5C9HYsUFWptSxohOy41wV3AbSzjHqEjxCt9MeJ4HXrLItti8Qr3fRBYgs45+L44bMZ9sA/EO+YiXQU9cQJb2qjK5EYQyFyEnGUMbh+zzRiCRQTI0A2nlnJ9zWQJr/4jIrlNJ6N0lV1GQzN/iIpCJto6ZmhbEgW5W3H+zB5qj72uKoyLlm8Lh+AF5ljtTnOuXgrh2nN6EN1hjRf52VtQZ93guIBkn5+riZ3gYYp3fl4sYbIAZRRs5rOcyFk9d/jo+kBw/Pxht4KABVHJHMPQ9cI2Fn2VbEOvZ+RrWLXc5Am3qwbUWpqYmp7n7wwdTrkYeCBMsXk7xQl5TJh+5Rkr6k0YRkcbvP+J+I1TJwob1DOyWBpRA3v9LYimEmy9eheQuKYzH5sQ/0r/7ZwhBL5/lB5kpv3kmwA7DZy1J5UbgChtSey3Du0N+6p/vgfybIgcZD5Csz8+dF3c+gZBCfRd4XpKgLoxLPZO69tM8/3z/3W0gOfXgEw6QKwJ6KoFXeBdRG9c/CCsR8dF3iIeZYWZvj+8nC/Y7hF6Dedr/6CHc0O4xwqE0GQzF3YUZI7HcqjxIIFsIsG+loUGWYB7a0HHn0FrAq79Q==
   <server_address> ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBLe8sKzXq4KReWp0Dz1lC8AKOcYNtPuk7GOqJRSVGkG1xRhP94gReTp7S1WnF6LgFt3vlC2k62BkSoXgryY3+8=
diff --git a/collections/federation/index.html b/collections/federation/index.html
index cac58e0..a6dccef 100644
--- a/collections/federation/index.html
+++ b/collections/federation/index.html
@@ -2,6 +2,6 @@
 EN
    FR

Federation

Open Terms Archive is a decentralised system. It aims at enabling any entity set up their own collections and track terms on their own.

In order to maximise discoverability, collaboration and political power, public collections are federated within a single ecosystem. This makes their data mutually discoverable and enables mutualising effort.

Benefits

A collection that joins the federation enjoys the following benefits:

  1. Visibility on the Open Terms Archive website lists of collections and datasets.
  2. Access to the Open Terms Archive GitHub organisation, administered by the Open Terms Archive core team.
  3. Collection logo provided by the Open Terms Archive core team.
  4. Referencing in the official collections list, enabling off-the-shelf discovery in the Federation API.
  5. Referencing in the official datasets list, providing visibility to analysts.
  6. Dedicated channel on the Open Terms Archive instant messaging system.
  7. API uptime tracking.
  8. Public announcement through all Open Terms Archive communication channels upon joining.

Criteria

A collection can join the Open Terms Archive federation if it abides by the following quality criteria:

  1. Clearly defined collection metadata.
  2. Clearly defined collection governance.
  3. The vast majority of versions are readable, as evidenced by a sample assessment.
  4. Frequency of at least one track a day, as evidenced by snapshots.
  5. Public and open-licensed declarations, as evidenced by the LICENSE file in the declarations repository.
  6. Public and open-licensed snapshots, as evidenced by the LICENSE file in the snapshots repository.
  7. Public and open-licensed versions, as evidenced by the LICENSE file in the versions repository.
  8. Regular, public, and open-licensed dataset releases, as evidenced by the LICENSE file in the datasets.
  9. Publicly accessible API with median response time under 20ms, as evidenced by uptime tracking logs.
  10. Abide by all Open Terms Archive software and data licenses.

How to join

An official request for joining the federation can be sent by the collection administrator or curator to the core team over email, GitHub or instant messages. That request should contain all necessary content or links that enable assessing the criteria.

The core team will confirm reception of the request and assess the criteria within 4 weeks. The result of the assessment will be provided to the requester through the same means the request was sent, along with a positive decision or a list of improvements that need to be done before a new request can be sent.

Once a positive decision has been issued, the core team will provide the requester with a timeline for joining the federation, on which they will jointly agree.

Disclaimer

Please note that establishing the federation is an ongoing effort. While criteria are assessed and refined to strike the right balance between accessibility and quality, the Open Terms Archive core team is responsible for assessing which collections may join the federation, and has the right to update the criteria as requests for joining are made.

The core team has the right to re-assess the federated status of any collection at any given time. In case the federated status of a collection is changed, the collection administrator will be informed immediately, and if possible before the action is made.

+Close

Federation

Open Terms Archive is a decentralised system. It aims at enabling any entity set up their own collections and track terms on their own.

In order to maximise discoverability, collaboration and political power, public collections are federated within a single ecosystem. This makes their data mutually discoverable and enables mutualising effort.

Benefits

A collection that joins the federation enjoys the following benefits:

  1. Visibility on the Open Terms Archive website lists of collections and datasets.
  2. Access to the Open Terms Archive GitHub organisation, administered by the Open Terms Archive core team.
  3. Collection logo provided by the Open Terms Archive core team.
  4. Referencing in the official collections list, enabling off-the-shelf discovery in the Federation API.
  5. Referencing in the official datasets list, providing visibility to analysts.
  6. Dedicated channel on the Open Terms Archive instant messaging system.
  7. API uptime tracking.
  8. Public announcement through all Open Terms Archive communication channels upon joining.

Criteria

A collection can join the Open Terms Archive federation if it abides by the following quality criteria:

  1. Clearly defined collection metadata.
  2. Clearly defined collection governance.
  3. The vast majority of versions are readable, as evidenced by a sample assessment.
  4. Frequency of at least one track a day, as evidenced by snapshots.
  5. Public and open-licensed declarations, as evidenced by the LICENSE file in the declarations repository.
  6. Public and open-licensed snapshots, as evidenced by the LICENSE file in the snapshots repository.
  7. Public and open-licensed versions, as evidenced by the LICENSE file in the versions repository.
  8. Regular, public, and open-licensed dataset releases, as evidenced by the LICENSE file in the datasets.
  9. Publicly accessible API with median response time under 20ms, as evidenced by uptime tracking logs.
  10. Abide by all Open Terms Archive software and data licenses.

How to join

An official request for joining the federation can be sent by the collection administrator or curator to the core team over email, GitHub or instant messages. That request should contain all necessary content or links that enable assessing the criteria.

The core team will confirm reception of the request and assess the criteria within 4 weeks. The result of the assessment will be provided to the requester through the same means the request was sent, along with a positive decision or a list of improvements that need to be done before a new request can be sent.

Once a positive decision has been issued, the core team will provide the requester with a timeline for joining the federation, on which they will jointly agree.

Disclaimer

Please note that establishing the federation is an ongoing effort. While criteria are assessed and refined to strike the right balance between accessibility and quality, the Open Terms Archive core team is responsible for assessing which collections may join the federation, and has the right to update the criteria as requests for joining are made.

The core team has the right to re-assess the federated status of any collection at any given time. In case the federated status of a collection is changed, the collection administrator will be informed immediately, and if possible before the action is made.

\ No newline at end of file diff --git a/collections/governance/index.html b/collections/governance/index.html index 8e8afa2..622a0cb 100644 --- a/collections/governance/index.html +++ b/collections/governance/index.html @@ -2,6 +2,6 @@ EN
FR

Collection governance

Setting up and maintaining a collection needs fulfilling certain tasks. These tasks are handled through roles. Each of these roles can be volunteer or paid, and can be handled by one single or several different entities. The Open Terms Archive core team provides processes and tools to support all of these roles.

Host

This role ensures that a server and internet access is available to run the engine on and fetch the terms, either by using its own infrastructure or renting a server on a hosting provider.

Administrator

This role takes responsibility for ensuring that the engine and associated software tools are functional and up to date.

Curator

This role decides which services and terms are welcome in the collection.

Maintainer

This role guarantees the quality of the tracked versions by reviewing contributions.

Contributor

This role adds declarations and keeps them up to date.

This optional role supports the existence of the collection by funding other roles, providing agent time, political support, or any other relevant non-operational contribution.

+Close

Collection governance

Setting up and maintaining a collection needs fulfilling certain tasks. These tasks are handled through roles. Each of these roles can be volunteer or paid, and can be handled by one single or several different entities. The Open Terms Archive core team provides processes and tools to support all of these roles.

Host

This role ensures that a server and internet access is available to run the engine on and fetch the terms, either by using its own infrastructure or renting a server on a hosting provider.

Administrator

This role takes responsibility for ensuring that the engine and associated software tools are functional and up to date.

Curator

This role decides which services and terms are welcome in the collection.

Maintainer

This role guarantees the quality of the tracked versions by reviewing contributions.

Contributor

This role adds declarations and keeps them up to date.

This optional role supports the existence of the collection by funding other roles, providing agent time, political support, or any other relevant non-operational contribution.

\ No newline at end of file diff --git a/collections/metadata/index.html b/collections/metadata/index.html index 60677fe..ab598ac 100644 --- a/collections/metadata/index.html +++ b/collections/metadata/index.html @@ -2,6 +2,6 @@ EN
FR

Collection metadata

A collection is defined by the following metadata.

Description

A concise description of the collection topic.

Examples

  • Largest global social media
  • Most used social media in France
  • Dating apps
  • Platforms providing services to businesses

Name

Three words maximum.

Examples

  • Platform Governance Archive
  • France Élections
  • Dating
  • P2B Compliance Assessment

ID

An identifier derived from the collection name that can more easily be referenced in code. Use acronyms and replace spaces with dashes.

Examples

  • pga
  • France-elections
  • dating
  • p2b-compliance

Language

The expected language of the terms in the collection.

Examples

  • English
  • French
  • All EU languages

Jurisdiction

The expected jurisdiction in which the terms in the collection apply.

Examples

  • EU
  • France
  • EEA
  • USA
  • global

Roles

The name, URL and logo of the entities that will take responsibility for each of the necessary governance roles.

+Close

Collection metadata

A collection is defined by the following metadata.

Description

A concise description of the collection topic.

Examples

  • Largest global social media
  • Most used social media in France
  • Dating apps
  • Platforms providing services to businesses

Name

Three words maximum.

Examples

  • Platform Governance Archive
  • France Élections
  • Dating
  • P2B Compliance Assessment

ID

An identifier derived from the collection name that can more easily be referenced in code. Use acronyms and replace spaces with dashes.

Examples

  • pga
  • France-elections
  • dating
  • p2b-compliance

Language

The expected language of the terms in the collection.

Examples

  • English
  • French
  • All EU languages

Jurisdiction

The expected jurisdiction in which the terms in the collection apply.

Examples

  • EU
  • France
  • EEA
  • USA
  • global

Roles

The name, URL and logo of the entities that will take responsibility for each of the necessary governance roles.

\ No newline at end of file diff --git a/contributing-terms/index.html b/contributing-terms/index.html index cf078b5..2a9eb1d 100644 --- a/contributing-terms/index.html +++ b/contributing-terms/index.html @@ -2,7 +2,7 @@ EN
FR

Contributing terms

Tracking new terms

Tracking terms is done by declaring them and the service they are associated with. Such a declaration is achieved by editing JSON files in the declarations folder.

Before adding new terms, open the declarations folder and check if the service you want to track terms for is already declared. If a JSON file with the name of the service is already present, you can jump straight to declaring terms. Otherwise, keep reading!

Declaring a new service

Before declaring a service, you will need to choose the service name and service ID. The service ID will be the name of the JSON file in which the service will be declared. It is a normalised version of the service name.

Service name

The service name is exposed to end users. It should reflect as closely as possible the official service name, as referenced in the terms or “about” pages, so that it can be recognised easily and unambiguously.

  • The service name should be the one used by the service itself, no matter the alphabet, UTF symbols, spaces, and casing.
    • Example: eBay.
    • Example: hi5.
    • Example: LINE.
    • Example: App Store.
    • Example: туту.ру (Cyrillic).
    • Example: 抖音短视频 (Simplified Chinese characters).
  • Domain name extensions (TLDs) are allowed when they are part of the official service name.
    • Example: Booking.com.
    • Example: historielærer.dk.
  • Service names can be prefixed by the provider name, separated by a space, when it would otherwise be too generic or ambiguous.
    • Example: Ads (by Facebook) → Facebook Ads.
    • Example: Analytics (by Google) → Google Analytics.
    • Example: Firebase (by Google) → Firebase.
    • Example: App Store (by Apple) → App Store.

If you have a hard time finding the service name, check out the practical guidelines to find the service name, and feel free to mention your uncertainties in the pull request! We will help you improve the service name if necessary 🙂

Service ID

The service ID is exposed to developers. It should be easy to handle with scripts and other tools.

  • Non-ASCII characters are not supported. Service IDs are derived from the service name by normalising it into ASCII.
    • Example: RTÉ → RTE.
    • Example: historielærer.dk → historielaerer.dk.
    • Example: туту.ру → tutu.ru.
    • Example: 抖音短视频 → Douyin.
  • Punctuation is supported, except characters that have meaning at filesystem level (:, /, \). These are replaced with a dash (-). The dot (.) is supported, but the service ID cannot be solely . or .. as these have specific meanings in the filesystem.
    • Example: Booking.com → Booking.com.
    • Example: Yahoo! → Yahoo!.
    • Example: re:start → re-start.
    • Example: we:// → we---.
  • Capitals and spaces are supported. Casing and spacing are expected to reflect the official service name casing and spacing.
    • Example: App Store → App Store.
    • Example: DeviantArt → DeviantArt.

If you have a hard time defining the service ID, check out the practical guidelines to derive the ID from the service name, and feel free to mention your uncertainties in the pull request! We will help you improve the service ID if necessary 🙂

More details on the ID and naming constraints and recommendations can be found in the relevant decision record.

Service declaration

Once you have the service name and the service ID, create a JSON file in the declarations folder named after the ID of the service you want to add, with the following structure:

{
+Close

Contributing terms

Tracking new terms

Tracking terms is done by declaring them and the service they are associated with. Such a declaration is achieved by editing JSON files in the declarations folder.

Before adding new terms, open the declarations folder and check if the service you want to track terms for is already declared. If a JSON file with the name of the service is already present, you can jump straight to declaring terms. Otherwise, keep reading!

Declaring a new service

Before declaring a service, you will need to choose the service name and service ID. The service ID will be the name of the JSON file in which the service will be declared. It is a normalised version of the service name.

Service name

The service name is exposed to end users. It should reflect as closely as possible the official service name, as referenced in the terms or “about” pages, so that it can be recognised easily and unambiguously.

  • The service name should be the one used by the service itself, no matter the alphabet, UTF symbols, spaces, and casing.
    • Example: eBay.
    • Example: hi5.
    • Example: LINE.
    • Example: App Store.
    • Example: туту.ру (Cyrillic).
    • Example: 抖音短视频 (Simplified Chinese characters).
  • Domain name extensions (TLDs) are allowed when they are part of the official service name.
    • Example: Booking.com.
    • Example: historielærer.dk.
  • Service names can be prefixed by the provider name, separated by a space, when it would otherwise be too generic or ambiguous.
    • Example: Ads (by Facebook) → Facebook Ads.
    • Example: Analytics (by Google) → Google Analytics.
    • Example: Firebase (by Google) → Firebase.
    • Example: App Store (by Apple) → App Store.

If you have a hard time finding the service name, check out the practical guidelines to find the service name, and feel free to mention your uncertainties in the pull request! We will help you improve the service name if necessary 🙂

Service ID

The service ID is exposed to developers. It should be easy to handle with scripts and other tools.

  • Non-ASCII characters are not supported. Service IDs are derived from the service name by normalising it into ASCII.
    • Example: RTÉ → RTE.
    • Example: historielærer.dk → historielaerer.dk.
    • Example: туту.ру → tutu.ru.
    • Example: 抖音短视频 → Douyin.
  • Punctuation is supported, except characters that have meaning at filesystem level (:, /, \). These are replaced with a dash (-). The dot (.) is supported, but the service ID cannot be solely . or .. as these have specific meanings in the filesystem.
    • Example: Booking.com → Booking.com.
    • Example: Yahoo! → Yahoo!.
    • Example: re:start → re-start.
    • Example: we:// → we---.
  • Capitals and spaces are supported. Casing and spacing are expected to reflect the official service name casing and spacing.
    • Example: App Store → App Store.
    • Example: DeviantArt → DeviantArt.

If you have a hard time defining the service ID, check out the practical guidelines to derive the ID from the service name, and feel free to mention your uncertainties in the pull request! We will help you improve the service ID if necessary 🙂

More details on the ID and naming constraints and recommendations can be found in the relevant decision record.

Service declaration

Once you have the service name and the service ID, create a JSON file in the declarations folder named after the ID of the service you want to add, with the following structure:

{
   "name": "<service name>",
   "documents": {}
 }
diff --git a/design-principles/index.html b/design-principles/index.html
index 186f7c8..d8f5bdd 100644
--- a/design-principles/index.html
+++ b/design-principles/index.html
@@ -2,6 +2,6 @@
 EN
FR

Design principles

These overarching principles guide technical and governance decisions. They are fundamental and can only be changed through community consensus, based on a thorough impact assessment.

Each principle has a name, a rationale, and potential implementation examples or guidelines.

1. Never trust the services

A major goal of Open Terms Archive is to enable assessing the loyalty of services towards their end users. Since loyalty is not assumed, trust can not be warranted.

Cases

Several services have been observed:

  • blocking an IP or a user agent randomly;
  • pretending to encounter technical errors (500, 502…) instead of being explicit about their intention (robots.txt, 403…);
  • to not reflect actual updates in the “last update” date of their contractual documents;
  • changing the content of the same page based on user agent properties or source IP geolocation. When one accesses a supposedly already regionalized policy according to the URL, but gets a different content based on geolocation without any information nor ability to access other regional policies, we consider it misleading and disloyal.

Examples of consequential choices

  • Do not use “last update” date in documents or headers for metadata.

2. Do not require trust in maintainers

Open Terms Archive maintainers should not need to be trusted by users more than the services it enables assessing.

Cases

  • Collections can be unmaintained.
  • Maintainers can filter out content that could be relevant from the perspective of other maintainers.
  • A server can encounter technical problems and miss updates.

Examples of consequential choices

  • Always keep an untouched snapshot of the source documents.
  • Use cryptographic signatures to ensure the database can be authenticated.
  • Enable terms collection to be replicated by anyone.
  • Support duplication across collections as this increases the resilience of the network. It will be up to reusers to decide which source they prefer in case of divergence.

3. Obtain documents like a user would

In order to guarantee legal relevance, source documents should only be ones that end users of the service are themselves receiving. Following principle 1, technical workarounds to obtain some version of the source documents that are more easily handled by machines cannot be trusted to have the same content as the ones intended for end users.

Cases

  • Accessing the same URL from a differently geolocated IP address will change the contents in some services.

Examples of consequential choices

  • Scrape HTML even if one could obtain the contractual content from an API.
+Close

Design principles

These overarching principles guide technical and governance decisions. They are fundamental and can only be changed through community consensus, based on a thorough impact assessment.

Each principle has a name, a rationale, and potential implementation examples or guidelines.

1. Never trust the services

A major goal of Open Terms Archive is to enable assessing the loyalty of services towards their end users. Since loyalty is not assumed, trust can not be warranted.

Cases

Several services have been observed:

  • blocking an IP or a user agent randomly;
  • pretending to encounter technical errors (500, 502…) instead of being explicit about their intention (robots.txt, 403…);
  • to not reflect actual updates in the “last update” date of their contractual documents;
  • changing the content of the same page based on user agent properties or source IP geolocation. When one accesses a supposedly already regionalized policy according to the URL, but gets a different content based on geolocation without any information nor ability to access other regional policies, we consider it misleading and disloyal.

Examples of consequential choices

  • Do not use “last update” date in documents or headers for metadata.

2. Do not require trust in maintainers

Open Terms Archive maintainers should not need to be trusted by users more than the services it enables assessing.

Cases

  • Collections can be unmaintained.
  • Maintainers can filter out content that could be relevant from the perspective of other maintainers.
  • A server can encounter technical problems and miss updates.

Examples of consequential choices

  • Always keep an untouched snapshot of the source documents.
  • Use cryptographic signatures to ensure the database can be authenticated.
  • Enable terms collection to be replicated by anyone.
  • Support duplication across collections as this increases the resilience of the network. It will be up to reusers to decide which source they prefer in case of divergence.

3. Obtain documents like a user would

In order to guarantee legal relevance, source documents should only be ones that end users of the service are themselves receiving. Following principle 1, technical workarounds to obtain some version of the source documents that are more easily handled by machines cannot be trusted to have the same content as the ones intended for end users.

Cases

  • Accessing the same URL from a differently geolocated IP address will change the contents in some services.

Examples of consequential choices

  • Scrape HTML even if one could obtain the contractual content from an API.
\ No newline at end of file diff --git a/en/sitemap.xml b/en/sitemap.xml index 8313e40..224da08 100644 --- a/en/sitemap.xml +++ b/en/sitemap.xml @@ -1 +1 @@ -https://docs.opentermsarchive.org/https://docs.opentermsarchive.org/collections/metadata/https://docs.opentermsarchive.org/api/node/https://docs.opentermsarchive.org/navigate-history/https://docs.opentermsarchive.org/api/collection/https://docs.opentermsarchive.org/collections/governance/https://docs.opentermsarchive.org/collections/create/https://docs.opentermsarchive.org/api/federation/https://docs.opentermsarchive.org/subscribe-rss/https://docs.opentermsarchive.org/contributing-terms/https://docs.opentermsarchive.org/collections/federation/https://docs.opentermsarchive.org/collections/https://docs.opentermsarchive.org/api/https://docs.opentermsarchive.org/guidelines/https://docs.opentermsarchive.org/design-principles/https://docs.opentermsarchive.org/guidelines/choosing-selectors/https://docs.opentermsarchive.org/guidelines/declaring/https://docs.opentermsarchive.org/memos/https://docs.opentermsarchive.org/guidelines/reviewing/https://docs.opentermsarchive.org/guidelines/targeting/https://docs.opentermsarchive.org/memos/writing-reference/ \ No newline at end of file +https://docs.opentermsarchive.org/https://docs.opentermsarchive.org/collections/metadata/https://docs.opentermsarchive.org/api/node/https://docs.opentermsarchive.org/navigate-history/https://docs.opentermsarchive.org/api/collection/https://docs.opentermsarchive.org/collections/governance/https://docs.opentermsarchive.org/collections/create/https://docs.opentermsarchive.org/api/federation/https://docs.opentermsarchive.org/subscribe-rss/https://docs.opentermsarchive.org/contributing-terms/https://docs.opentermsarchive.org/collections/federation/https://docs.opentermsarchive.org/collections/https://docs.opentermsarchive.org/api/https://docs.opentermsarchive.org/guidelines/https://docs.opentermsarchive.org/design-principles/https://docs.opentermsarchive.org/guidelines/choosing-selectors/https://docs.opentermsarchive.org/memos/copywriting-reference/https://docs.opentermsarchive.org/guidelines/declaring/https://docs.opentermsarchive.org/memos/how-to-publish/https://docs.opentermsarchive.org/memos/https://docs.opentermsarchive.org/guidelines/reviewing/https://docs.opentermsarchive.org/guidelines/targeting/ \ No newline at end of file diff --git a/guidelines/choosing-selectors/index.html b/guidelines/choosing-selectors/index.html index 21bd2dc..c6bd8c1 100644 --- a/guidelines/choosing-selectors/index.html +++ b/guidelines/choosing-selectors/index.html @@ -2,7 +2,7 @@ EN
FR

Choosing selectors

Selectors are used in Open Terms Archive declarations to specify the parts of documents that should be recorded.

What are selectors

Selectors are used in the select and remove keys of an Open Terms Archive declaration.

The “selectors” referred to are defined by the W3C Selectors standard, more commonly known as “CSS Selectors”.

An easy-to-read introduction to CSS Selectors can be found on mdn web docs.

Choosing durable selectors eases maintenance

The design of web pages containing terms can evolve over time, leading to changes in their HTML (more precisely, to their DOM) which may render ineffective the selectors that were initially chosen. That means they may no longer target the significant parts, breaking the ability to continuously record terms changes. When this happens, selectors must be updated to specify the meaningful parts of the terms.

It is possible to reduce the frequency of human intervention on the selectors by choosing some that are least likely to become obsolete even when changes occur on the document structure. Decreasing the cost of this maintenance increases the likelihood that terms are continuously tracked.

Guidelines

While there is no single right way to choose durable selectors, as it remains intrinsically subjective and dependent on the document itself, following the guidelines below is likely to yield durable selectors.

Simple

Prefer simple selectors over compound ones, and compound ones over combinator ones, as they are more readable and make less assumptions on future changes.

In particular, avoid deep nesting of elements and pseudo-classes. Such selectors rely not only on the targeted content structure but also on the content around it. The likelihood that at least one block in the tree changes on a page update increases, making the selector brittle.

Examples

  • #content or [role="main"] are better than #content .inner or [role="main"] > .content-block.
  • main > div > #article > .tos is a bad selector because of deep nesting.
  • div:nth-child(2) is a bad selector because of the usage of a pseudo-class.

Named

Prefer selectors whose names are representative of the parts they select, as they are evidence of an intention by the service provider, and thus more likely to stay valid through design changes.

Conversely, avoid class names being or containing series of alphanumeric characters. Those are most likely to be generated and to change on the next page update.

Examples

  • .tos or #legal-notice are better than main or .content.
  • .dez68h or .tos-cpoxw27 are bad selectors because they are likely automatically generated.
Example with HTML

For the following HTML code:

...
+Close

Choosing selectors

Selectors are used in Open Terms Archive declarations to specify the parts of documents that should be recorded.

What are selectors

Selectors are used in the select and remove keys of an Open Terms Archive declaration.

The “selectors” referred to are defined by the W3C Selectors standard, more commonly known as “CSS Selectors”.

An easy-to-read introduction to CSS Selectors can be found on mdn web docs.

Choosing durable selectors eases maintenance

The design of web pages containing terms can evolve over time, leading to changes in their HTML (more precisely, to their DOM) which may render ineffective the selectors that were initially chosen. That means they may no longer target the significant parts, breaking the ability to continuously record terms changes. When this happens, selectors must be updated to specify the meaningful parts of the terms.

It is possible to reduce the frequency of human intervention on the selectors by choosing some that are least likely to become obsolete even when changes occur on the document structure. Decreasing the cost of this maintenance increases the likelihood that terms are continuously tracked.

Guidelines

While there is no single right way to choose durable selectors, as it remains intrinsically subjective and dependent on the document itself, following the guidelines below is likely to yield durable selectors.

Simple

Prefer simple selectors over compound ones, and compound ones over combinator ones, as they are more readable and make less assumptions on future changes.

In particular, avoid deep nesting of elements and pseudo-classes. Such selectors rely not only on the targeted content structure but also on the content around it. The likelihood that at least one block in the tree changes on a page update increases, making the selector brittle.

Examples

  • #content or [role="main"] are better than #content .inner or [role="main"] > .content-block.
  • main > div > #article > .tos is a bad selector because of deep nesting.
  • div:nth-child(2) is a bad selector because of the usage of a pseudo-class.

Named

Prefer selectors whose names are representative of the parts they select, as they are evidence of an intention by the service provider, and thus more likely to stay valid through design changes.

Conversely, avoid class names being or containing series of alphanumeric characters. Those are most likely to be generated and to change on the next page update.

Examples

  • .tos or #legal-notice are better than main or .content.
  • .dez68h or .tos-cpoxw27 are bad selectors because they are likely automatically generated.
Example with HTML

For the following HTML code:

...
   <div id="globalContainer" role="main">
     <div class="tos_title clearfix">Privacy Policy</div>
     <div class="article_content" id="tos_content">
diff --git a/guidelines/declaring/index.html b/guidelines/declaring/index.html
index 62e3d60..423e1be 100644
--- a/guidelines/declaring/index.html
+++ b/guidelines/declaring/index.html
@@ -2,7 +2,7 @@
 EN
FR

This document presents practical guidelines, is edited collaboratively and is not normative. Normative constraints are exposed in Contributing Terms.

Declaring documents

Service name

Casing

  • In order to find the service name casing, rely first on the page title (easily found in search results). Do not rely on the logo as it can be stylized differently. Example with Facebook: +Close

This document presents practical guidelines, is edited collaboratively and is not normative. Normative constraints are exposed in Contributing Terms.

Declaring documents

Service name

Casing

  • In order to find the service name casing, rely first on the page title (easily found in search results). Do not rely on the logo as it can be stylized differently. Example with Facebook: facebook search
  • If it is still ambiguous, rely on Wikipedia as a source. However, make sure to differentiate the service from the provider company’s name. Example with “DeviantArt”, a service (which used to be stylized deviantArt until 2014) by the limited liability company “deviantArt”: deviantArt search

Terms used by several services

  • If you want to add terms which happen to be shared with another service from the same parent company, be specific in naming the exact service you want to track. For instance, you may find that a company like Github uses the same terms for its code hosting and its AI assistant. While this does not mean that the terms for GitHub (code hosting) are the only terms of GitHub Copilot (assistant), it does mean that these two services have terms that are represented in the same document. In tracking terms for one of these services, say Github Copilot, be specific in naming it as the service you want to track. This way, if GitHub was to introduce dedicated terms for each of these services in the future, their locations can be updated without having to create new terms since the service already existed before.

Service ID

Normalisation

  1. For non-roman alphabets (Cyrillic, ideograms…), use the service-provided transliteration.
  2. For diacritics: normalise the string to its NFD normal UTF form, then remove the entire combining character class. Details.
  3. As a last resort, use the domain name.

Provider prefixing

  • If you encounter a document you want to add to a service, yet find that it would override an already-declared document for this service such as Terms of Service or Privacy Policy, and that the only solution you see would be to create a new terms type that would contain the name of the feature, then it is likely you should declare a new service, potentially duplicating existing documents.

Example: the Facebook Community Payments terms are Terms of Service. The only way to declare them in the Facebook service would be to add a “Community Payments Terms” terms type as they would otherwise conflict with Facebook’s Terms of Service. It is better to declare a new service called “Facebook Payments” with its own Terms of Service. It turns out that this service also has a developer agreement, independent from the main Facebook service.

Facebook Community Payments

  • As a last resort, rely on the trademark.

Example: Apple’s App Store uses only generic terms (“app” and “store”). However, it is of common use to mention “the App Store” as Apple’s. To help us decide whether it should be prefixed or not, we can check that Apple has trademarked “App Store”. The service can thus be named “App Store”, without prefixing.

Usual noise

Noise is unwanted content in versions.

Irrelevant content

The first type of noise we try to remove is content that is not relevant legally speaking, and that harms document readability.

CSS selectors are a first step as they permit to select an area instead of the whole page, but they let pass through content such as headers, footers, buttons, drop-down lists…

Filtering permits to get rid of the remaining irrelevant content.

A drop-down list let user select which document he would like to see but this list doesn’t interest us in the final document.

HTML file :

<div class="filter-holder">
   <select class="filter-options">
diff --git a/guidelines/reviewing/index.html b/guidelines/reviewing/index.html
index 540bd6a..6a7bad3 100644
--- a/guidelines/reviewing/index.html
+++ b/guidelines/reviewing/index.html
@@ -2,7 +2,7 @@
 EN
FR

Reviewing contributions

Thank you for showing interest in reviewing contributions made to Open Terms Archive. This document is intended to help you get started and provide some guidelines for reviewing contributions.

Why is this important?

We want to make sure that the contributions made to the project are of high quality and that they are in line with the vision of the project. We also want to make sure that the contributions are reviewed in a timely manner so that the contributors can get feedback and continue to contribute to the project. +Close

Reviewing contributions

Thank you for showing interest in reviewing contributions made to Open Terms Archive. This document is intended to help you get started and provide some guidelines for reviewing contributions.

Why is this important?

We want to make sure that the contributions made to the project are of high quality and that they are in line with the vision of the project. We also want to make sure that the contributions are reviewed in a timely manner so that the contributors can get feedback and continue to contribute to the project. This is where volunteer reviewers come in to help. Reviewers are people who have volunteered to review contributions made to the project. They are not paid for their work, but they are given credit for their work.

Who can do it?

Anyone can review contributions. As hinted before, most of the contributions made to Open Terms Archive are contractual documents that are to be tracked. Therefore, you don’t need to be a programmer or have any technical knowledge. You just need to be able to read and understand the contribution and provide feedback where necessary.

How long and complex will it be?

It depends on the contribution. Some contributions may be spot on and can be reviewed in a few minutes. Other contributions may require a more detailed review and changes to be made and can take longer. We estimate it to take 3 to 15 mins for one to review a document. The first reviews might be a bit longer as reviewers get familiar with the process, and will speed up with time.

Where to start

To get started, we will need to understand a few things. The nature of the contributions you will be reviewing, where to get the contributions to review and the tools that will help you in reviewing the contributions.

The nature of the contributions

The contributions you will be reviewing are contractual documents of digital services. These are documents that govern the relationship between two or more parties. They are not the original documents, but rather the terms extracted from these documents. If the terms are represented accurately, it will be easier to follow on with any subsequent changes in the document. Contributors track these documents (sometimes, anonymously) by submitting a pull request either using a tool that helps contributors add documents to the project, the GUI contributing tool, or by creating a JSON file and adding it via a pull request. You can find more information about pull requests here.

There are three types of contributions you’ll come across:

  • adding declarations to a collection;
  • updating declarations in a collection;
  • removing declarations from a collection.

The method used to review each of these types of contribution varies, and you’ll find a detailed explanation below.

Where to find the contributions

The contributions can be found in the form of pull requests in the repository of the collection you want to work on. For example, for the Contrib collection, they are visible under the pull requests tab of the contrib-declarations repository..

How To Review Pull Requests that Add Declarations

Your focus should be on two aspects: accuracy and quality.

  • Accuracy is about making sure that the contributed declaration is accurate and tracks significant sections of the terms that actually make a legal impact when updated.
  • Durability is about making sure that the contributed declaration is durable over time, with CSS selectors that will make sure the document will need little maintenance over time.

Step-by-step Review Guide

  1. Click on the Inspect the declaration link to view the declaration in a graphical user interface.
  2. Use the link provided in the URL section of the contribution tool to check out the original document.
  3. Verify that the name of the service matches the JSON file and complies with the guidelines.
  4. Quickly scan the document to ensure that the correct term type has been selected. To determine the term type, consider who the intended audience is and what the document is discussing. You can also refer to the terms types list to find the best term type for the document.
  5. Confirm that the selected area of the document contains only one term type and does not include any other types.
  6. Check both the significant and insignificant parts of the document. Ensure that the suggested selectors abide by the selectors guidelines.
    • Ensure that the significant parts do not include navigation items, contact links, or other insignificant details that may cause confusion by triggering a change detection when the legal terms have actually not been updated.
  7. Verify the version of the document in the contribution tool by clicking on the Verify version button.
  8. Ensure that all checks generated by the OTA-bot are manually checked.
  9. When you confirm that the term contribution has been made to the correct collection, proceed to add a review.
  10. Merge the contribution.

How To Review Pull Requests that Update Declarations

When some terms can no longer be tracked by the Open Terms Archive engine, an issue is created in the collection repository. This issue contains the details on why the document cannot be tracked and the date the challenge was encountered. diff --git a/guidelines/targeting/index.html b/guidelines/targeting/index.html index 89692c6..e1c02ce 100644 --- a/guidelines/targeting/index.html +++ b/guidelines/targeting/index.html @@ -2,6 +2,6 @@ EN

FR

What to track?

Can I track terms that are not applicable yet?

Yes.

For example, documents that would start applying at date in the future are legitimate candidates for tracking. You can this way track if their terms change even before they are applied.

+Close

What to track?

Can I track terms that are not applicable yet?

Yes.

For example, documents that would start applying at date in the future are legitimate candidates for tracking. You can this way track if their terms change even before they are applied.

\ No newline at end of file diff --git a/index.html b/index.html index e0f3de5..cde9987 100644 --- a/index.html +++ b/index.html @@ -2,7 +2,7 @@ EN
FR

The document you are reading now is targeted at developers wanting to use or contribute to the engine of Open Terms Archive. For a high-level overview of Open Terms Archive’s wider goals and processes, please read its public homepage.

Open Terms Archive Engine

This codebase is a Node.js module enabling downloading, archiving and publishing versions of documents obtained online. It can be used independently from the Open Terms Archive ecosystem.

Motivation

Words in bold are business domain names.

Services have terms written in documents, contractual (Terms of Services, Privacy Policy…) or not (Community Guidelines, Deceased User Policy…), that can change over time. Open Terms Archive enables users rights advocates, regulatory bodies and interested citizens to follow the changes to these terms, to be notified whenever a new version is published, to explore their entire history and to collaborate in analysing them. This free and open-source engine is developed to support these goals.

Main concepts

Collection

Open Terms Archive is a decentralised system. It aims at enabling any entity to track terms on its own. To that end, the Open Terms Archive engine can be run on any server, thus making it a dedicated instance. An instance tracks terms within a single collection.

A collection is characterised by a scope across dimensions that describe the terms it tracks, such as language, jurisdiction and industry.

Example scope

The terms tracked in this collection are:

  • Of dating services used in Europe.
  • In the European Union and Switzerland jurisdictions.
  • In English, unless no English version exists, in which case the primary official language of the jurisdiction of incorporation of the service operator will be used.

Federation

In order to maximise discoverability, collaboration and political power, public collections are federated within a single ecosystem. This makes their data mutually discoverable and enables mutualising effort.

Terms types

To distinguish between the different terms of a service, each has a type, such as “Terms of Service”, “Privacy Policy”, “Developer Agreement”…

This type matches the topic, but not necessarily the title the service gives to it. Unifying the types enables comparing terms across services.

More information on terms types can be found in the dedicated repository. They are published on NPM under @opentermsarchive/terms-types, enabling standardisation and interoperability beyond the Open Terms Archive engine.

Declarations

The terms that constitute a collection are defined in simple JSON files called declarations.

A declaration also contains some metadata on the service on which the terms apply.

Here is an example declaration tracking the Privacy Policy of Open Terms Archive:

{
+Close

The document you are reading now is targeted at developers wanting to use or contribute to the engine of Open Terms Archive. For a high-level overview of Open Terms Archive’s wider goals and processes, please read its public homepage.

Open Terms Archive Engine

This codebase is a Node.js module enabling downloading, archiving and publishing versions of documents obtained online. It can be used independently from the Open Terms Archive ecosystem.

Motivation

Words in bold are business domain names.

Services have terms written in documents, contractual (Terms of Services, Privacy Policy…) or not (Community Guidelines, Deceased User Policy…), that can change over time. Open Terms Archive enables users rights advocates, regulatory bodies and interested citizens to follow the changes to these terms, to be notified whenever a new version is published, to explore their entire history and to collaborate in analysing them. This free and open-source engine is developed to support these goals.

Main concepts

Collection

Open Terms Archive is a decentralised system. It aims at enabling any entity to track terms on its own. To that end, the Open Terms Archive engine can be run on any server, thus making it a dedicated instance. An instance tracks terms within a single collection.

A collection is characterised by a scope across dimensions that describe the terms it tracks, such as language, jurisdiction and industry.

Example scope

The terms tracked in this collection are:

  • Of dating services used in Europe.
  • In the European Union and Switzerland jurisdictions.
  • In English, unless no English version exists, in which case the primary official language of the jurisdiction of incorporation of the service operator will be used.

Federation

In order to maximise discoverability, collaboration and political power, public collections are federated within a single ecosystem. This makes their data mutually discoverable and enables mutualising effort.

Terms types

To distinguish between the different terms of a service, each has a type, such as “Terms of Service”, “Privacy Policy”, “Developer Agreement”…

This type matches the topic, but not necessarily the title the service gives to it. Unifying the types enables comparing terms across services.

More information on terms types can be found in the dedicated repository. They are published on NPM under @opentermsarchive/terms-types, enabling standardisation and interoperability beyond the Open Terms Archive engine.

Declarations

The terms that constitute a collection are defined in simple JSON files called declarations.

A declaration also contains some metadata on the service on which the terms apply.

Here is an example declaration tracking the Privacy Policy of Open Terms Archive:

{
   "name": "Open Terms Archive",
   "documents": {
     "Privacy Policy": {
diff --git a/index.xml b/index.xml
index 24cafcb..dfaff00 100644
--- a/index.xml
+++ b/index.xml
@@ -24,8 +24,11 @@ Each principle has a name, a rationale, and potential implementation examples or
 What are selectors Selectors are used in the select and remove keys of an Open Terms Archive declaration.
 The “selectors” referred to are defined by the W3C Selectors standard, more commonly known as “CSS Selectors”.
 An easy-to-read introduction to CSS Selectors can be found on mdn web docs.
-Choosing durable selectors eases maintenance The design of web pages containing terms can evolve over time, leading to changes in their HTML (more precisely, to their DOM) which may render ineffective the selectors that were initially chosen.Declaring documentshttps://docs.opentermsarchive.org/guidelines/declaring/Mon, 01 Jan 0001 00:00:00 +0000https://docs.opentermsarchive.org/guidelines/declaring/This document presents practical guidelines, is edited collaboratively and is not normative. Normative constraints are exposed in Contributing Terms.
-Declaring documents Service name Casing In order to find the service name casing, rely first on the page title (easily found in search results). Do not rely on the logo as it can be stylized differently. Example with Facebook: If it is still ambiguous, rely on Wikipedia as a source. However, make sure to differentiate the service from the provider company&rsquo;s name.Reviewing contributionshttps://docs.opentermsarchive.org/guidelines/reviewing/Mon, 01 Jan 0001 00:00:00 +0000https://docs.opentermsarchive.org/guidelines/reviewing/Reviewing contributions Thank you for showing interest in reviewing contributions made to Open Terms Archive. This document is intended to help you get started and provide some guidelines for reviewing contributions.
+Choosing durable selectors eases maintenance The design of web pages containing terms can evolve over time, leading to changes in their HTML (more precisely, to their DOM) which may render ineffective the selectors that were initially chosen.Copywriting referencehttps://docs.opentermsarchive.org/memos/copywriting-reference/Mon, 01 Jan 0001 00:00:00 +0000https://docs.opentermsarchive.org/memos/copywriting-reference/Copywriting reference Each memo must be composed of the elements detailed below. You must follow this structure when writing your memos.
+Title Write a short declarative sentence to highlight the key change. 140 characters maximum. Use the name of the service as the subject. Write in the present tense. Prefer active phrasings over passive (e.g., “Microsoft expands reach” rather than “Reach expanded by Microsoft“). Describe the policy change, not the name of the document.Declaring documentshttps://docs.opentermsarchive.org/guidelines/declaring/Mon, 01 Jan 0001 00:00:00 +0000https://docs.opentermsarchive.org/guidelines/declaring/This document presents practical guidelines, is edited collaboratively and is not normative. Normative constraints are exposed in Contributing Terms.
+Declaring documents Service name Casing In order to find the service name casing, rely first on the page title (easily found in search results). Do not rely on the logo as it can be stylized differently. Example with Facebook: If it is still ambiguous, rely on Wikipedia as a source. However, make sure to differentiate the service from the provider company&rsquo;s name.How to publish a memohttps://docs.opentermsarchive.org/memos/how-to-publish/Mon, 01 Jan 0001 00:00:00 +0000https://docs.opentermsarchive.org/memos/how-to-publish/How to publish a memo This guide will help you publish a memo on opentermsarchive.org/en/memos.
+No technical skills are required.
+Prerequisites A drafted memo compliant with the copywriting reference. 1. Send Send your memo to contact@opentermsarchive.org by writing it in the body of the email or as a file attachment. Feel free to add any comments or questions you may have about the content or format.
+2. Review The Open Terms Archive core team will review your memo as quickly as possible.Reviewing contributionshttps://docs.opentermsarchive.org/guidelines/reviewing/Mon, 01 Jan 0001 00:00:00 +0000https://docs.opentermsarchive.org/guidelines/reviewing/Reviewing contributions Thank you for showing interest in reviewing contributions made to Open Terms Archive. This document is intended to help you get started and provide some guidelines for reviewing contributions.
 Why is this important? We want to make sure that the contributions made to the project are of high quality and that they are in line with the vision of the project. We also want to make sure that the contributions are reviewed in a timely manner so that the contributors can get feedback and continue to contribute to the project.Targetinghttps://docs.opentermsarchive.org/guidelines/targeting/Mon, 01 Jan 0001 00:00:00 +0000https://docs.opentermsarchive.org/guidelines/targeting/What to track? Can I track terms that are not applicable yet? Yes.
-For example, documents that would start applying at date in the future are legitimate candidates for tracking. You can this way track if their terms change even before they are applied.Writing referencehttps://docs.opentermsarchive.org/memos/writing-reference/Mon, 01 Jan 0001 00:00:00 +0000https://docs.opentermsarchive.org/memos/writing-reference/Writing reference Each memo must be composed of the elements detailed below. You must follow this structure when writing your memos.
-Title Write a short declarative sentence to highlight the key change. 140 characters maximum. Use the name of the service as the subject. Write in the present tense. Prefer active phrasings over passive (e.g., “Microsoft expands reach” rather than “Reach expanded by Microsoft“). Describe the policy change, not the name of the document.
\ No newline at end of file
+For example, documents that would start applying at date in the future are legitimate candidates for tracking. You can this way track if their terms change even before they are applied.
\ No newline at end of file
diff --git a/jsdoc/Record.html b/jsdoc/Record.html
index 1434468..d4d9441 100644
--- a/jsdoc/Record.html
+++ b/jsdoc/Record.html
@@ -161,7 +161,7 @@ 
Home
Classes
  • 
 
 
 
 
diff --git a/jsdoc/archivist_extract_index.js.html b/jsdoc/archivist_extract_index.js.html
index 353c732..3ab7847 100644
--- a/jsdoc/archivist_extract_index.js.html
+++ b/jsdoc/archivist_extract_index.js.html
@@ -236,7 +236,7 @@ 
    Home
    Classes
    • 
 
 
 
 
diff --git a/jsdoc/archivist_fetcher_index.js.html b/jsdoc/archivist_fetcher_index.js.html
index 8cad333..a41cc96 100644
--- a/jsdoc/archivist_fetcher_index.js.html
+++ b/jsdoc/archivist_fetcher_index.js.html
@@ -83,7 +83,7 @@ 
      Home
      Classes
      • 
 
 
 
 
diff --git a/jsdoc/archivist_recorder_record.js.html b/jsdoc/archivist_recorder_record.js.html
index dc4ba55..1c1f6e7 100644
--- a/jsdoc/archivist_recorder_record.js.html
+++ b/jsdoc/archivist_recorder_record.js.html
@@ -88,7 +88,7 @@ 
        Home
        Classes
        • 
 
 
 
 
diff --git a/jsdoc/archivist_recorder_repositories_interface.js.html b/jsdoc/archivist_recorder_repositories_interface.js.html
index 909e4a6..fa71dc0 100644
--- a/jsdoc/archivist_recorder_repositories_interface.js.html
+++ b/jsdoc/archivist_recorder_repositories_interface.js.html
@@ -169,7 +169,7 @@ 
          Home
          Classes
          • 
 
 
 
 
diff --git a/jsdoc/collection-api_routes_services.js.html b/jsdoc/collection-api_routes_services.js.html
index 9102a96..18a057e 100644
--- a/jsdoc/collection-api_routes_services.js.html
+++ b/jsdoc/collection-api_routes_services.js.html
@@ -201,7 +201,7 @@ 
            Home
            Classes
            • 
 
 
 
 
diff --git a/jsdoc/collection-api_routes_versions.js.html b/jsdoc/collection-api_routes_versions.js.html
index 1c3aedf..409fe7e 100644
--- a/jsdoc/collection-api_routes_versions.js.html
+++ b/jsdoc/collection-api_routes_versions.js.html
@@ -152,7 +152,7 @@ 
              Home
              Classes
              • 
 
 
 
 
diff --git a/jsdoc/global.html b/jsdoc/global.html
index dc71098..c44ee74 100644
--- a/jsdoc/global.html
+++ b/jsdoc/global.html
@@ -846,7 +846,7 @@ 
                Home
                Classes
                • 
 
 
 
 
diff --git a/jsdoc/index.html b/jsdoc/index.html
index d8c940e..4f29113 100644
--- a/jsdoc/index.html
+++ b/jsdoc/index.html
@@ -56,7 +56,7 @@ 
                  Home
                  Classes
                  • 
 
 
 
 
diff --git a/memos/copywriting-reference/index.html b/memos/copywriting-reference/index.html
new file mode 100644
index 0000000..adcf6c9
--- /dev/null
+++ b/memos/copywriting-reference/index.html
@@ -0,0 +1,7 @@
+Open Terms Archive - Copywriting reference
                    
+
                    Copywriting reference
                    Each memo must be composed of the elements detailed below. You must follow this structure when writing your memos.
                    Title
                    • Write a short declarative sentence to highlight the key change.
                    • 140 characters maximum.
                    • Use the name of the service as the subject.
                    • Write in the present tense.
                    • Prefer active phrasings over passive (e.g., “Microsoft expands reach” rather than “Reach expanded by Microsoft“).
                    • Describe the policy change, not the name of the document. This information will be given in the metadata below.
                    • Use no punctuation.
                    • Do not put a link in the title because in some reuse contexts the entire title is a link to the memo.
                    Example
                    • Facebook bans States from denying the use of violence in an invasion
                    • OpenAI specifies further plugin exports rules
                    Service name
                    • Write the service name (not the company name, e.g., “Facebook” rather than “Meta“)
                    Examples
                    LinkedIn
                    OpenAI
                    Terms types
                    • You must fill a valid terms type.
                    • Multiple terms types are allowed.
                    Examples
                    Terms of Service
                    Community Guidelines, Terms of Service, Privacy Policy
                    Date modified
                    • Use Month Day, Year format.
                    • Multiples dates are allowed.
                    • Avoid repeating months or years
                    Examples
                    March 4, 2024
                    November 3, 10 - December 16, 2023
                    Body text
                    • Describe changes in a neutral, objective, non-judgmental manner.
                      • Write in the past tense (e.g., “added”, “removed”…).
                      • Bolden the most important point.
                      • Do not repeat the date, it is already in the metadata.
                    • Systematically add a link to the diff on this action verb.
                      • Title of the link: “See the change”.
                      • Avoid verbs like “announce”, because most of the time the changes detected are not announced.
                    • Do not hesitate to quote the new text.
                      • Do not italicise citations, use quotes.
                      • Minimise the length of citations because legal text is often very wordy.
                      • Only quote the text before modification if it is strictly necessary to understand the change, to reduce the risk of confusion and length.
                    • If you write in a different language than the detected change, always look for citations in the version of the document that matches the language of writing if it exists instead of translating them yourself.
                    Example
                    OpenAI specified that, as far as European (EEA and Swiss) developers were concerned, their Agreement is with OpenAI Ireland Ltd. OpenAI stopped acting as a separate controller of personal data, and developers now have to present a privacy notice to their users prior to processing their data.
                    OpenAI also extended export restrictions to plugins “located” in countries embargoed or sanctioned by the US. This provision previously concerned only plugin owners.
                    OpenAI Ireland Ltd is a Dublin-based subsidiary of OpenAI set up in 2023.
                    Complete examples
                    Memo 1
                    Midjourney strengthens policies on intellectual property infringements
                    Midjourney ▪ Terms of Service ▪ December 23, 2023_
                    Midjourney introduced an explicit prohibition regarding the infringement of others’ intellectual property rights in its conditions for service availability and quality, mentioning the possibility of legal action and permanent ban from the service.
                    Previously, legal action was only mentioned where the violation of intellectual property rights resulted in financial detriment to Midjourney.
                    Memo 2
                    Instagram adds a posting ban to protect copyright
                    Instagram ▪ Community Guidelines ▪ March 28, 2022
                    On March 28, Instagram updated its intellectual property community rules, prohibiting the posting of content that “facilitates copyright infringement through unauthorized devices or services.” The text presents a list of cases in which users would risk infringing the copyright of a third party or even merely “facilitating” such infringement, even if they did not intend to do so. After the previously listed cases, which include “you purchased or downloaded the content” or “you saw others post the same content,” Instagram adds that users risk infringing copyright if they “use an unauthorized streaming device or service (examples: a ‘jailbroken’ or ‘loaded’ app or service).”
                    Contextualisation (optional)
                    • Body text in a new paragraph: contextualisation with external links to the most authoritative sources available.
                    • For example, explain which wider problems are tackled by this policy change, or give a historical perspective on the change.
                    Example
                    Meta expands reach against child exploitation
                    Facebook ▪ Community Guidelines ▪ June 13, 2022
                    The section on child exploitation for both Facebook and Instagram expanded to cover not only publications that exploit minors, but also “any activity” related to such acts.
                    This opens up the question of moderation of private discussions, as social platforms show difficulties in managing content related to child abuse —as recently as late March, the New York Times showed that moderation remains very light in this area, even though platforms are supposed to list this type of content and report it to authorities.
                    Source: June 23, 2022 Memo on French Elections.
                    
+
+
\ No newline at end of file
diff --git a/memos/how-to-publish/index.html b/memos/how-to-publish/index.html
new file mode 100644
index 0000000..287b023
--- /dev/null
+++ b/memos/how-to-publish/index.html
@@ -0,0 +1,7 @@
+Open Terms Archive - How to publish a memo
                    
+
                    How to publish a memo
                    This guide will help you publish a memo on opentermsarchive.org/en/memos.
                    No technical skills are required.
                    Prerequisites
                    1. Send
                    Send your memo to contact@opentermsarchive.org by writing it in the body of the email or as a file attachment. Feel free to add any comments or questions you may have about the content or format.
                    2. Review
                    The Open Terms Archive core team will review your memo as quickly as possible.
                    If necessary, we will suggest changes and discuss them with you. Note that review times may vary depending on the number of changes required, the speed of exchanges, and the availability of reviewers. If you do not hear from us within two weeks, please do not hesitate to contact us again by the means of your choice.
                    3. Promote
                    Once the core team has published your memo on opentermsarchive.org/en/memos, we will inform you and provide you with the URL address of your memo. You should then promote it through the media and to the people you consider appropriate. Whenever possible, please associate the hashtag #TermsSpotting with your memo promotion, in order to provide visibility to the overall Open Terms Archive project and analysis.
                    
+
+
\ No newline at end of file
diff --git a/memos/index.xml b/memos/index.xml
index 8b6b6b9..cc5d519 100644
--- a/memos/index.xml
+++ b/memos/index.xml
@@ -1,2 +1,5 @@
-Memos on Open Terms Archive documentationhttps://docs.opentermsarchive.org/memos/Recent content in Memos on Open Terms Archive documentationHugo -- gohugo.ioenWriting referencehttps://docs.opentermsarchive.org/memos/writing-reference/Mon, 01 Jan 0001 00:00:00 +0000https://docs.opentermsarchive.org/memos/writing-reference/Writing reference Each memo must be composed of the elements detailed below. You must follow this structure when writing your memos.
-Title Write a short declarative sentence to highlight the key change. 140 characters maximum. Use the name of the service as the subject. Write in the present tense. Prefer active phrasings over passive (e.g., “Microsoft expands reach” rather than “Reach expanded by Microsoft“). Describe the policy change, not the name of the document.
\ No newline at end of file
+Memos on Open Terms Archive documentationhttps://docs.opentermsarchive.org/memos/Recent content in Memos on Open Terms Archive documentationHugo -- gohugo.ioenCopywriting referencehttps://docs.opentermsarchive.org/memos/copywriting-reference/Mon, 01 Jan 0001 00:00:00 +0000https://docs.opentermsarchive.org/memos/copywriting-reference/Copywriting reference Each memo must be composed of the elements detailed below. You must follow this structure when writing your memos.
+Title Write a short declarative sentence to highlight the key change. 140 characters maximum. Use the name of the service as the subject. Write in the present tense. Prefer active phrasings over passive (e.g., “Microsoft expands reach” rather than “Reach expanded by Microsoft“). Describe the policy change, not the name of the document.How to publish a memohttps://docs.opentermsarchive.org/memos/how-to-publish/Mon, 01 Jan 0001 00:00:00 +0000https://docs.opentermsarchive.org/memos/how-to-publish/How to publish a memo This guide will help you publish a memo on opentermsarchive.org/en/memos.
+No technical skills are required.
+Prerequisites A drafted memo compliant with the copywriting reference. 1. Send Send your memo to contact@opentermsarchive.org by writing it in the body of the email or as a file attachment. Feel free to add any comments or questions you may have about the content or format.
+2. Review The Open Terms Archive core team will review your memo as quickly as possible.
\ No newline at end of file
diff --git a/memos/writing-reference/index.html b/memos/writing-reference/index.html
deleted file mode 100644
index 861d486..0000000
--- a/memos/writing-reference/index.html
+++ /dev/null
@@ -1,7 +0,0 @@
-Open Terms Archive - Writing reference
                    
-
                    Writing reference
                    Each memo must be composed of the elements detailed below. You must follow this structure when writing your memos.
                    Title
                    • Write a short declarative sentence to highlight the key change.
                    • 140 characters maximum.
                    • Use the name of the service as the subject.
                    • Write in the present tense.
                    • Prefer active phrasings over passive (e.g., “Microsoft expands reach” rather than “Reach expanded by Microsoft“).
                    • Describe the policy change, not the name of the document. This information will be given in the metadata below.
                    • Use no punctuation.
                    • Do not put a link in the title because in some reuse contexts the entire title is a link to the memo.
                    Example
                    • Facebook bans States from denying the use of violence in an invasion
                    • OpenAI specifies further plugin exports rules
                    Service name
                    • Write the service name (not the company name, e.g., “Facebook” rather than “Meta“)
                    Examples
                    LinkedIn
                    OpenAI
                    Terms types
                    • You must fill a valid terms type.
                    • Multiple terms types are allowed.
                    Examples
                    Terms of Service
                    Community Guidelines, Terms of Service, Privacy Policy
                    Date modified
                    • Use Month Day, Year format.
                    • Multiples dates are allowed.
                    • Avoid repeating months or years
                    Examples
                    March 4, 2024
                    November 3, 10 - December 16, 2023
                    Body text
                    • Describe changes in a neutral, objective, non-judgmental manner.
                      • Write in the past tense (e.g., “added”, “removed”…).
                      • Bolden the most important point.
                      • Do not repeat the date, it is already in the metadata.
                    • Systematically add a link to the diff on this action verb.
                      • Title of the link: “See the change”.
                      • Avoid verbs like “announce”, because most of the time the changes detected are not announced.
                    • Do not hesitate to quote the new text.
                      • Do not italicise citations, use quotes.
                      • Minimise the length of citations because legal text is often very wordy.
                      • Only quote the text before modification if it is strictly necessary to understand the change, to reduce the risk of confusion and length.
                    • If you write in a different language than the detected change, always look for citations in the version of the document that matches the language of writing if it exists instead of translating them yourself.
                    Example
                    OpenAI specified that, as far as European (EEA and Swiss) developers were concerned, their Agreement is with OpenAI Ireland Ltd. OpenAI stopped acting as a separate controller of personal data, and developers now have to present a privacy notice to their users prior to processing their data.
                    OpenAI also extended export restrictions to plugins “located” in countries embargoed or sanctioned by the US. This provision previously concerned only plugin owners.
                    OpenAI Ireland Ltd is a Dublin-based subsidiary of OpenAI set up in 2023.
                    Full examples
                    Memo 1
                    Midjourney strengthens policies on intellectual property infringements
                    Midjourney ▪ Terms of Service ▪ December 23, 2023_
                    Midjourney introduced an explicit prohibition regarding the infringement of others’ intellectual property rights in its conditions for service availability and quality, mentioning the possibility of legal action and permanent ban from the service.
                    Previously, legal action was only mentioned where the violation of intellectual property rights resulted in financial detriment to Midjourney.
                    Memo 2
                    Instagram adds a posting ban to protect copyright
                    Instagram ▪ Community Guidelines ▪ March 28, 2022
                    On March 28, Instagram updated its intellectual property community rules, prohibiting the posting of content that “facilitates copyright infringement through unauthorized devices or services.” The text presents a list of cases in which users would risk infringing the copyright of a third party or even merely “facilitating” such infringement, even if they did not intend to do so. After the previously listed cases, which include “you purchased or downloaded the content” or “you saw others post the same content,” Instagram adds that users risk infringing copyright if they “use an unauthorized streaming device or service (examples: a ‘jailbroken’ or ‘loaded’ app or service).”
                    Contextualisation (optional)
                    • Body text in a new paragraph: contextualisation with external links to the most authoritative sources available.
                    • For example, explain which wider problems are tackled by this policy change, or give a historical perspective on the change.
                    Example
                    Meta expands reach against child exploitation
                    Facebook · Community Guidelines · June 13, 2022
                    The section on child exploitation for both Facebook and Instagram expanded to cover not only publications that exploit minors, but also “any activity” related to such acts.
                    This opens up the question of moderation of private discussions, as social platforms show difficulties in managing content related to child abuse —as recently as late March, the New York Times showed that moderation remains very light in this area, even though platforms are supposed to list this type of content and report it to authorities.
                    Source: June 23, 2022 Memo on French Elections.
                    
-
-
\ No newline at end of file
diff --git a/navigate-history/index.html b/navigate-history/index.html
index 2f523e4..ccf9b5a 100644
--- a/navigate-history/index.html
+++ b/navigate-history/index.html
@@ -2,6 +2,6 @@
 EN
                    FR

Browsing through terms

Every collection offers a public database of versions they recorded.

For this guide, we will use the example of the Demo collection. The terms of this collection are published on the OpenTermsArchive/demo-versions repository.

  • From the repository page, open the folder of the service of your choice by clicking on it. For example, GitHub:

    Demo-versions repository services list

  • You will see the set of terms tracked for that service, now click on the terms of your choice. For example, GitHub’s Privacy Policy:

    GitHub terms list

  • The most recent version will be displayed. To view the history of changes made to these terms, click on History at the top right:

    GitHub Privacy Policy

  • The changes are presented in reverse chronological order. For example, GitHub Privacy Policy history. Click on a change title to see its contents:

    GitHub Privacy Policy history

  • The red colour shows deleted words and the green colour shows added words. For example, in this change of GitHub Privacy Policy, you can see in red the deletion of information about GitHub data protection officer.

    One GitHub Privacy Policy change with source diff view

  • You can choose from two types of display with the icons in the grey bar above the document. The first one (which is also the default one), named source diff displays the previous version and the next one either side by side or in a consolidated way (with one line under the other). The second one, named rich diff displays all the changes in a single document. In this view, beyond green and red, the yellow color shows modified paragraphs. Be careful, this display does not show some changes such as hyperlinks and text style’s changes:

    One GitHub Privacy Policy change with rich diff view

Notes

  • For long documents, unchanged paragraphs will not be displayed by default. You can manually make them appear by clicking on the small arrows just above or just below the displayed paragraphs:

    Expand unchanged paragraphs on source diff view

    or

    Expand unchanged paragraphs on rich diff view

  • You can use the History button anywhere in the repository to display the history of changes made to all terms in the current folder.

+Close

Browsing through terms

Every collection offers a public database of versions they recorded.

For this guide, we will use the example of the Demo collection. The terms of this collection are published on the OpenTermsArchive/demo-versions repository.

  • From the repository page, open the folder of the service of your choice by clicking on it. For example, GitHub:

    Demo-versions repository services list

  • You will see the set of terms tracked for that service, now click on the terms of your choice. For example, GitHub’s Privacy Policy:

    GitHub terms list

  • The most recent version will be displayed. To view the history of changes made to these terms, click on History at the top right:

    GitHub Privacy Policy

  • The changes are presented in reverse chronological order. For example, GitHub Privacy Policy history. Click on a change title to see its contents:

    GitHub Privacy Policy history

  • The red colour shows deleted words and the green colour shows added words. For example, in this change of GitHub Privacy Policy, you can see in red the deletion of information about GitHub data protection officer.

    One GitHub Privacy Policy change with source diff view

  • You can choose from two types of display with the icons in the grey bar above the document. The first one (which is also the default one), named source diff displays the previous version and the next one either side by side or in a consolidated way (with one line under the other). The second one, named rich diff displays all the changes in a single document. In this view, beyond green and red, the yellow color shows modified paragraphs. Be careful, this display does not show some changes such as hyperlinks and text style’s changes:

    One GitHub Privacy Policy change with rich diff view

Notes

  • For long documents, unchanged paragraphs will not be displayed by default. You can manually make them appear by clicking on the small arrows just above or just below the displayed paragraphs:

    Expand unchanged paragraphs on source diff view

    or

    Expand unchanged paragraphs on rich diff view

  • You can use the History button anywhere in the repository to display the history of changes made to all terms in the current folder.

\ No newline at end of file diff --git a/subscribe-rss/index.html b/subscribe-rss/index.html index 2cbc175..ac5992a 100644 --- a/subscribe-rss/index.html +++ b/subscribe-rss/index.html @@ -2,6 +2,6 @@ EN
FR

Subscribing to terms changes

An RSS feed is a type of web page that contains information about the latest content published by a website, such as the date of publication and the address where you can view it. When this resource is updated, a feed reader app automatically notifies you and you can see the update. You can receive notification for a specific service or document by subscribing to RSS feeds.

For a specific document

To find out the address of the RSS feed you want to subscribe to:

  1. Navigate to the page with the history of changes you are interested in.
    • For example, for the GitHub Privacy Policy of the Demo instance, this would be this page.
  2. Copy the address of that page from your browser’s address bar.
    • For example, for the GitHub Privacy Policy of the Demo instance, this would be https://github.com/OpenTermsArchive/demo-versions/commits/main/GitHub/Privacy%20Policy.md.
  3. Append .atom at the end of this address.
    • For example, for the GitHub Privacy Policy of the Demo instance, this would become https://github.com/OpenTermsArchive/demo-versions/commits/main/GitHub/Privacy%20Policy.md.atom.
  4. Subscribe your RSS feed reader to the resulting address.

For all the documents of a service

Simply navigate to the history of changes for the service you are interested in and follow the same procedure as for a specific document.

For example, for all GitHub documents of the Demo instance, you would obtain https://github.com/OpenTermsArchive/demo-versions/commits/main/GitHub.atom.

For all the documents of an instance

Simply append commits.atom to the URL of the repository.

For example, for all documents of the Demo instance, you would use https://github.com/OpenTermsArchive/demo-versions/commits.atom.

+Close

Subscribing to terms changes

An RSS feed is a type of web page that contains information about the latest content published by a website, such as the date of publication and the address where you can view it. When this resource is updated, a feed reader app automatically notifies you and you can see the update. You can receive notification for a specific service or document by subscribing to RSS feeds.

For a specific document

To find out the address of the RSS feed you want to subscribe to:

  1. Navigate to the page with the history of changes you are interested in.
    • For example, for the GitHub Privacy Policy of the Demo instance, this would be this page.
  2. Copy the address of that page from your browser’s address bar.
    • For example, for the GitHub Privacy Policy of the Demo instance, this would be https://github.com/OpenTermsArchive/demo-versions/commits/main/GitHub/Privacy%20Policy.md.
  3. Append .atom at the end of this address.
    • For example, for the GitHub Privacy Policy of the Demo instance, this would become https://github.com/OpenTermsArchive/demo-versions/commits/main/GitHub/Privacy%20Policy.md.atom.
  4. Subscribe your RSS feed reader to the resulting address.

For all the documents of a service

Simply navigate to the history of changes for the service you are interested in and follow the same procedure as for a specific document.

For example, for all GitHub documents of the Demo instance, you would obtain https://github.com/OpenTermsArchive/demo-versions/commits/main/GitHub.atom.

For all the documents of an instance

Simply append commits.atom to the URL of the repository.

For example, for all documents of the Demo instance, you would use https://github.com/OpenTermsArchive/demo-versions/commits.atom.

\ No newline at end of file