Skip to content

Latest commit

 

History

History
95 lines (53 loc) · 8.18 KB

CONTRIBUTING.md

File metadata and controls

95 lines (53 loc) · 8.18 KB

First of all, thanks for taking the time to contribute! 🎉👍

Table of Contents


Add new Terms Types

Every terms tracked in Open Terms Archive must have a type. Each service can have only one terms of a given type.

If you need to track some terms for a service, you might encounter cases when no matching type seems to be available in the list of supported terms types.

Open a discussion

First of all, double-check that the type you consider adding does not already exist in the database. If it does, use the associated type for tracking.

If not, then check the open discussions in this repository to make sure that there is not already a discussion about the type you consider adding.

If no discussion seems to match the type you are interested in adding, start a new discussion.

Note that service-specific types (such as “Twitter Privacy Policy”) are not allowed. Terms types aim at allowing comparisons across services and should thus be generic.

Integration process

Qualification

New suggestions for terms types are categorized as Submitted. The Core Team reviews these suggestions and ensures that all the necessary information is gathered and clear and that at least 5 examples are provided, maximizing industry and jurisdiction diversity. Once that is the case, the discussion is moved to the Qualified category and opened up to the community.

Community outreach

Once your suggestion is Qualified, publicize it across Open Terms Archive channels and engage with the community. This will enable multiple perspectives to be shared, yielding a clear and reusable proposal that maximises usage. Throughout the discussion, the data should be critically examined, especially taking into account international perspectives on vocabulary and the variety of definitions across jurisdictions.

Community feedback is expressed in the following ways:

  • ⬆️ upvoting types suggestions that seem relevant for their field of work, thereby increasing their priority and visibility among other suggested types;
  • 🚀 reacting with a rocket emoji to a suggestion that seems acceptable as it is, thereby supporting its integration;
  • 💬 commenting on a suggestion to describe potential improvements or limitations, thereby evolving the suggestion.

Integration

Integration is done on a consent basis, meaning that no remark is blocking the suggestion from moving forward. After at least 2 weeks have passed since the suggestion was initially opened or last changed, and once all pending remarks have been solved, a pull request for addition to the database can be submitted. To facilitate tracking and participation, each pull request should contain only one type addition and must link to the corresponding discussion. The Core Team will then review and potentially merge the pull request.

Governance considerations

Considering the decentralised and distributed usage of Open Terms Archive, it is very impactful to remove types.

The addition process is thus designed to add significant friction to the addition of new terms types, to ensure that only those that have demonstrated reusability and adoption are added to the database.

The process itself, while progressively formalised, still provides ample arbitrary control to the Core Team, in order to avoid loopholes that could lead to mass additions. As the process is more regularly used, this power will be progressively reduced to make the community more autonomous.

List a new contributor

We acknowledge the efforts of our contributors by listing them on our website and this is made possible by the use of the All Contributors bot.

All Contributors enables adding a contributor with a comment on an issue or pull request, without writing code. To do this, please use the dedicated issue on this repository.

Please read the following contributing guide.

Changelog

When opening a pull request, it is required to fill in the changelog. It must be determined whether the changes made to the codebase impact users or not. These two cases are mutually exclusive and have different implications.

Modified terms types or data structure

All changes to the codebase that impact users must be documented in the CHANGELOG.md file, following the Common Changelog format with these additional specifications:

  1. The unreleased section of Keep a Changelog must be added in the changelog with the addition of a tag to specify which type of release should be published and to foster discussions about it inside pull requests. This tag should be one of the names mandated by SemVer, within brackets: [patch], [minor] or [major]. For example: ### Unreleased [minor].
    Changes that require an adjustment in the infrastructure, they are considered as a breaking change in order to notify Collection operators about the need to update their deployment dependency accordingly.

  2. Each listed change must provide an actionable way to adapt the user’s codebase, either directly in the changelog or through instructions or links.

  3. Changes should be a single sentence without punctuation, following Common Changelog examples.

  4. Since each release is produced automatically from a single pull request, the notice links to the source pull request rather than references, which would always reference the same pull request. References can link to relevant parts of an RFC, decision record, or diff. This notice is automatically generated by the CI during the release process and should not be added manually.

  5. The notice is also used to present sponsor information and it is required. Since the development of this project is funded by different actors, and following discussions with sponsors, financial contributions are acknowledged in the changelog itself. The format of the notice thus diverges from the Common Changelog specification in that it is not “a single-sentence paragraph”. Sponsor information is in quote format, starts with “Development of this release was supported by <funding_from>”, and provides the name and link to the sponsor, as well as information on the specific funding instrument, as specified by the sponsor itself or as required by law. A short message from the sponsor might also be added, as long as it abides by the community’s Code of Conduct and aligns with the project’s goals. For volunteer contributions, the sentence should start with: “Development of this release was made on a volunteer basis by <contributor_name>”

Changes that do not impact users

For non-functional changes (e.g., documentation, CI workflows) that do not impact users and should not trigger a release, it must be clearly indicated that documenting these changes in the changelog is unnecessary by adding the following content in its entirety to the changelog:

## Unreleased [no-release]

_Modifications made in this changeset do not add, remove or alter any behavior, dependency, API or functionality of the software. They only change non-functional parts of the repository, such as the README file or CI workflows._

This content will be automatically deleted by the CI after merging.