📖 Update Branch-Protection admin and non-admin requirements

docs/checks/internal/checks.yaml

@@ -154,7 +154,7 @@ checks:
       status checks before acceptance into a main branch, or preventing rewriting of
       public history.
 
-      Note: The following settings queried by the Branch-Protection check require an admin token: `DismissStaleReviews`, `EnforceAdmin`, `StrictStatusCheck` and `RequireCodeownerReview`. If
+      Note: The following settings queried by the Branch-Protection check require an admin token: `DismissStaleReviews`, `EnforceAdmins`, `RequireLastPushApproval`, `RequiresStatusChecks` and `UpToDateBeforeMerge`. If
       the provided token does not have admin access, the check will query the branch
       settings accessible to non-admins and provide results based only on these settings.
       Even so, we recommend using a non-admin token, which provides a thorough enough
@@ -191,27 +191,27 @@ checks:
 
       This test has tiered scoring. Each tier must be fully satisfied to achieve points at the next tier. For example, if you fulfill the Tier 3 checks but do not fulfill all the Tier 2 checks, you will not receive any points for Tier 3.
 
-      Note: If Scorecard is run without an administrative access token, the requirements that specify “For administrators” are ignored.
+      Note: If Scorecard is run without an administrative access token, the requirements that specify “For administrators” can be safely ignored, and scores will be determined as if all such requirements have been met.
 
       Tier 1 Requirements (3/10 points):
         - Prevent force push
         - Prevent branch deletion
         - For administrators: Include administrator for review
 
       Tier 2 Requirements (6/10 points):
-        - Required reviewers >=1
-        - For administrators: Last push review
-        - For administrators: Strict status checks (require branches to be up-to-date before merging)
+        - Require at least 1 reviewer for approval before merging
+        - For administrators: Require branch to be up to date before merging
+        - For administrators: Require approval of the most recent reviewable push
 
       Tier 3 Requirements (8/10 points):
-        - Status checks defined
+        - Require branch to pass at least 1 status check before merging
 
       Tier 4 Requirements (9/10 points):
-        - Required reviewers >= 2
+        - Require at least 2 reviewers for approval before merging
+        - Require review from code owners
 
       Tier 5 Requirements (10/10 points):
-        - For administrators: Dismiss stale reviews
-        - For administrators: Require CODEOWNER review
+        - For administrators: Dismiss stale reviews and approvals when new commits are pushed
 
       GitLab Integration Status:
         - GitLab associates releases with commits and not with the branch. Releases are ignored in this portion of the scoring.

docs/faq.md

@@ -15,6 +15,7 @@ This page answers frequently asked questions about Scorecard, including its purp
   - [Pinned-Dependencies: Will Scorecard detect unpinned dependencies in tests with Dockerfiles?](#pinned-dependencies-will-scorecard-detect-unpinned-dependencies-in-tests-with-dockerfiles)
   - [Pinned-Dependencies: Can I use version pinning instead of hash pinning?](#pinned-dependencies-can-i-use-version-pinning-instead-of-hash-pinning)
   - [Signed-Releases: Why sign releases?](#signed-releases-why-sign-releases)
+  - [Branch-Protection: How to setup a 10/10 branch protection on GitHub?](#branch-protection-how-to-setup-a-1010-branch-protection-on-github)
 
 ---
 
@@ -89,3 +90,28 @@ Currently, the main benefit of [signed releases](checks.md#signed-releases) is t
 However, there are already moves to make it even more relevant. For example, the OpenSSF is working on [implementing signature verification for NPM packages](https://github.blog/2022-08-08-new-request-for-comments-on-improving-npm-security-with-sigstore-is-now-open/) which would allow a consumer to automatically verify if the package they are downloading was generated through a reliable builder and if it is correctly signed.
 
 Signing releases already has some relevance and it will soon offer even more security benefits for both consumers and maintainers.
+
+### Branch-Protection: How to setup a 10/10 branch protection on GitHub?
+
+To get a 10/10 score for Branch-Protection check using a non-admin token, you should have the following settings for your branches:
+
+![GitHub's branch protection settings with the following options selected: "Require a pull request before merging", "Require approvals" with 1 approver, "Require review from Code Owners", "Require status checks to pass before merging", "Require branches to be up to date before merging", and have at least one Status Check chosen. All other options are unchecked.](/docs/design/images/branch-protection-settings-non-admin-token.png)
+
+When using an admin token, Scorecard can verify if a few other important settings are ensured:
+
+![GitHub's branch protection settings with the following options selected: "Require a pull request before merging", "Require approvals" with 2 approvers, "Dismiss stale pull request approvals when new commits are pushed", "Require review from Code Owners", "Require approval of the most recent reviewable push", "Require status checks to pass before merging", "Require branches to be up to date before merging", have at least one Status Check chosen, and "Do not allow bypassing the above settings". All other options are unchecked.](/docs/design/images/branch-protection-settings-admin-token.png)
+
+It's important to reiterate that Branch-Protection score is Tier-based. If a setting from Tier 1 is not satisfied, it does not matter that all other settings are met, the score will be truncated up the Tier's maximum. In this case, 3/10. The following table shows the relation between branch protection settings on GitHub and the score Tier:
+
+| Name                                                                                                     | Status                          | Required only for admin token | Tier |
+| -------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------- | ---- |
+| Allow force pushes                                                                                       | Disabled                        | -                             | 1    |
+| Allow deletions                                                                                          | Disabled                        | -                             | 1    |
+| Do not allow bypassing the above settings                                                                | Enabled                         | Yes                           | 1    |
+| Require a pull request before merging > Require Approvals                                                | Enabled with at least 1         | -                             | 2    |
+| Require status checks to pass before merging > Require branches to be up to date before merging          | Enabled                         | Yes                           | 2    |
+| Require a pull request before merging > Require approval of the most recent reviewable push              | Enabled                         | Yes                           | 2    |
+| Require status checks to pass before merging > Status Checks                                             | At least 1                      | -                             | 3    |
+| Require a pull request before merging > Require Approvals                                                | Enabled with at least 2         | -                             | 4    |
+| Require a pull request before merging > Require review from Code Owners                                  | Enabled and has CODEOWNERS file | -                           | 4    |
+| Require a pull request before merging > Dismiss stale pull request approvals when new commits are pushed | Enabled                         | Yes                           | 5    |