Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Jump to bottom

Improve reviewer guidelines #74

Merged
merged 3 commits into from
Sep 6, 2023
Merged

Improve reviewer guidelines #74

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7faeb95
Added new sections to the guideline
emmanuellar Aug 29, 2023
4285d54
Accept Clifford's changes to the reviewer guidelines
emmanuellar Sep 3, 2023
66d39b4
Fix md linting issues
Cli4d Sep 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 37 additions & 27 deletions content/guidelines/reviewing.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ Thank you for showing interest in reviewing contributions made to Open Terms Arc

## Why is this important?

Open Terms Archive is a open source project that tracks, analyses and disseminates changes to contractual documents with the aim of shiflting the balance of power from big tech to end users.
As such we get lots of contributions involving various contractual documents. However, 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.
Open Terms Archive is an open source project that tracks, analyses and disseminates changes to contractual documents with the aim of shiflting the balance of power from big tech to end users.
As such, we get lots of contributions involving various contractual documents. However, 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?
Expand All @@ -23,55 +23,65 @@ However we approximate it to take about 3-15 mins for one to review a document,

## Where to start

To get started we will need to understand a number 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 review the contributions.
To get started, we will need to understand a number 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.
The contributions you will be reviewing are not the original documents, but rather accurate tracking and data about these documents. If the documents are represented accurately, it will be easier to follow on with any subsequent changes in the document.
They are not the original documents, but rather accurate tracking and data about these documents. If the documents 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 the **GUI contributing tool** (A tool that helps contributors add documents to the project), or creating a JSON file and adding it via a pull request. You can find more information about pull requests [here](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)

### Where to get the contributions to review
There are three types of contributions you'll come across:

For these contributions, you will get them in the [`contrib-declarations`](https://github.com/OpenTermsArchive/contrib-declarations) repository under the pull requests tab. You can find the pull requests [here](https://github.com/OpenTermsArchive/contrib-declarations/pulls).
- Adding contributions to declarations
- Updating contributions to declarations
- Removal contributions to declarations

### Tools that will help you in review the contributions
The method used to review each of these types of contribution varies, and you'll find a detailed explanation of this as you proceed with this document.

The contributions are in the form of pull requests. Pull requests are a way of submitting contributions to a repository. You can find more information about pull requests [here](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests).
The pull requests can be opened in 2 ways:
### Where to find the contributions

- By a bot. The bot will open a pull request when contributors add documents using the **contribution tool** which is a tool that helps contributors add documents to the project.
- By the contributor. The contributor can open a pull request manually by following the steps when they track the document by **creating a JSON file** and adding it via a pull request.
These contributions are housed in the [`contrib-declarations`](https://github.com/OpenTermsArchive/contrib-declarations) repository under the pull requests tab. You can find the pull requests [here](https://github.com/OpenTermsArchive/contrib-declarations/pulls).

## How to review
## How To Review Pull Requests that Add Declarations

When reviewing the contributions, your focus should be on two things: accuracy and quality.
When a contribution is made using the contribution tool, the OTA-bot will create a pull request. This pull request typically consists of several checks, which guides the reviewer on the key things to look out for during the review process, and a link to inspect the delaration.

You should focus should be on two things: accuracy and quality.

- Accuracy is about making sure that the contribution document is accurate and tracks **significant** sections that actually make a legal impact when changed.

- Quality is about making sure that the contribution is of high quality and uses stable CSS selectors that will make sure the document will need less maintainace over time.

### Step-by-step Review Guide Draft
### Step-by-step Review Guide

1. Inspect the declaration suggestion
2. Use the link provided in the contribution tool to check out the original document.
3. Verify that the name of the service matches the JSON file.
1. Click on the inspect the declaration suggestion link to view contribution using the contribution tool.
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](https://docs.opentermsarchive.org/guidelines/declaring/#service-name).
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 type guide](https://github.com/OpenTermsArchive/terms-types/blob/main/termsTypes.json) 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 only [simple/basic selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors/Selectors_and_combinators#basic_selectors) are used and avoid complex selectors like [combinators](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors/Selectors_and_combinators#combinators) and [pseudo selectors](https://www.w3schools.com/css/css_pseudo_elements.asp). To simplify try to avoid selectors with indexes/numbers e.g `:nth-child(n)` and avoid selectors with long chains e.g. `div > body > .aside > p > span > a )`
- Ensure that only [simple/basic selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors/Selectors_and_combinators#basic_selectors) are used and avoid complex selectors like [combinators](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors/Selectors_and_combinators#combinators) and [pseudo selectors](https://www.w3schools.com/css/css_pseudo_elements.asp). To simplify, try to avoid selectors with indexes/numbers e.g `:nth-child(n)` and long chains e.g. `div > body > .aside > p > span > a )`
- Ensure that the significant parts do not include a table of contents, contact links, or other insignificant details that may cause confusion by giving a false impression of change.
7. Verify the version of the document in the contribution tool to see how it will appear.
8. If everything is in order, confirm that the term contribution has been made to the correct collection.
9. Merge the contribution.
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 Updating Terms

### Making Changes to a Contribution

When you spot an error in a contribution, instead of asking them to implement these changes, we usually recommend you fix it, especially for first time contributors,in order to save time. Make your corrections directly through the contribution tool, and send the document. Doing this, will create an update in the already existing pull request and a new comment will be generated by the OTA-bot.

In some special cases, the correction may have to do with the service name. Such changes modify the branch name, hence, creating a new pull request instead of updating the initial pull request as their names are now different. In any case, it's always important to let the contributor know about any changes or corrections you make to their contribution.

#### Contributions FAQ

1. **Why is it important to use simple CSS selectors for selecting and removing significant and insignificant parts respectively?** It is important to use simple selectors to have greater stability. The more simple the selectors are the more stable the document will be
1. **Why is it important to use simple CSS selectors for selecting and removing significant and insignificant parts respectively?** It is important to use simple selectors to have greater stability. The more simple the selectors are the more stable the document will be stable.

2. **How can we tell if a section is insignificant in the contractual document?** The best way to judge if a section doesn't not fit into the contractual document is by asking yourself if a change made on that section has any legal impact. If not it can be viewed insignificant
2. **How can we tell if a section is insignificant in the contractual document?** The best way to judge if a section doesn't not fit into the contractual document is by asking yourself if a change made on that section has any legal impact. If not it can be viewed insignificant.

3. **What should I do if removing a small insignificant part leads to complex CSS selectors?** If you are trying to remove a small insignificant section like a contact part in a document and it brings up complex CSS selectors, we would prefer you leave that minor section. It is better to have more stable documents that accurate ones that are more tideous to maintain.
3. **What should I do if removing a small insignificant part leads to complex CSS selectors?** If you are trying to remove a small insignificant section like a contact part in a document and it brings up complex CSS selectors, we would prefer you leave that minor section. It is better to have stable documents than accurate ones that are tideous to maintain.

4. **How do we give feedback when reviewing a pull request?** Even though there will be contributors who are technically skilled and those who aren't you are encouraged to provide comments line by line in the pull request for more context and to provide suggestions
4. **How do we give feedback when reviewing a pull request?** Even though there will be contributors who are technically skilled and those who aren't, you are encouraged to provide comments line by line in the pull request for more context and to provide suggestions.

5. **Do we suggest changes and leave it up to them to make changes?** It is encouraged to empower contributors to make required changes themselves, however for first time contributors, you can make the changes and explain why they are neccessary as they progressively learn. In due time they get better at it and can make changes on their own.
5. **How do we suggest changes to a contributor?** It is encouraged to empower contributors to make required changes themselves, however for first time contributors, you can make the changes and explain why they are neccessary as they progressively learn. In due time they get better at it and can make changes on their own.