Add Library Registry access control system

Background
----------

The Arduino Library Manager Registry repository receives thousands of pull requests from a large number of community
contributors. The great majority of these contributors behave in a responsible manner. Unfortunately this repository is
regularly the subject of irresponsible behavior. The small number of people who behave irresponsibly consume a
significant amount of the finite maintenance resources available for maintenance of Arduino's repositories.

Communication is always the first measure taken in these cases. This is done automatically by the "Manage PRs" workflow,
and then by the registry maintainer when it becomes clear that the user has disregarded the comments from the bot.
Unfortunately it is regularly the case that the user simply disregards all communication and continues their pattern of
irresponsible behavior unchecked.

Alternatives
------------

GitHub provides tools for dealing with harmful behavior:

- Report user
- Block user

Reporting a user is the appropriate measure in cases of malicious behavior, and the account is usually banned from the
site relatively quickly after a legitimate report is made. However, the irresponsible behavior in the registry
repository is not overtly malicious and so reporting the user in these cases would not be appropriate or effective.

At first glance, the block feature seems ideal. However, it can only be done at an organization-wide level, and by an
organization administrator. The repository maintainer is not an organization administrator, so this makes the feature
inconvenient to use. There is no sign of these users interacting with other repositories in the `arduino` organization,
and so there is no benefit to blocking them at organization scope. In addition, in order to make it more difficult to
circumvent the access restriction, we need the ability to block requests for libraries owned by an entity who has
established a pattern of irresponsible behavior, regardless of which user submits the request.

So the tools provided by GitHub are not suitable and a bespoke system must be implemented.

Access Levels
-------------

Allow: the user may submit requests for any library, even if registry privileges have been revoked for the owner of the
library's repository. This access level will only be granted to registry maintainers, in order to allow them to make
exceptions for specific libraries owned by an entity whose privileges have been revoked.

Default: the user may submit requests for any library, unless registry privileges have been revoked for the owner of the
library's repository.

Deny: the user may not submit requests. Requests from users with "default" access level for any library repository owned
by the entity (user or organization) are denied.

In cases where a request is declined due to revocation of Library Manager Registry privileges, the "Manage PRs" workflow
will automatically make an explanatory comment, including a link that provides more details about the cause of the
revocation. It will also close the PR in the case where it is not possible for the requester to resolve the problem:

* The requester's Library Manager Registry privileges have been revoked

**-OR-**

* The owners of all library repositories which are the subject of the request have lost Library Manager Registry
privileges.

Author: per1234

.github/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributor Guide
+
+Thanks for your interest in contributing to the **Arduino Library Manager Registry**!
+
+## Support and Discussion
+
+If you would like to request assistance or discuss the **Library Manager Registry**, please make a topic on **Arduino Forum**:
+
+https://forum.arduino.cc/c/17
+
+## Registration and Maintenance
+
+---
+
+⚠ If you behave irresponsibly in your interactions with this repository, your Library Manager Registry privileges will be revoked.
+
+Carefully read and follow the instructions in any comments the bot and human maintainers make on your pull requests. If you are having trouble following the instructions, add a comment that provides a detailed description of the problem you are having and a human maintainer will provide assistance.
+
+Although we have set up automation for the most basic tasks, this repository is maintained by humans. So behave in a manner appropriate for interacting with humans, including clearly communicating what you are hoping to accomplish.
+
+---
+
+If you would like to submit a library, or request registry maintenance for a library already in the registry, please follow the instructions provided in the documentation:
+
+[**Click here to see the documentation**](../README.md#table-of-contents)
+
+Make sure to read the relevant sections of the FAQ:
+
+[**Click here to see the FAQ**](../FAQ.md#table-of-contents)

.github/workflows/manage-prs.yml

@@ -125,6 +125,7 @@ jobs:
     runs-on: ubuntu-latest
 
     outputs:
+      conclusion: ${{ steps.parse-request.outputs.conclusion }}
       type: ${{ steps.parse-request.outputs.type }}
       error: ${{ steps.parse-request.outputs.error }}
       arduinoLintLibraryManagerSetting: ${{ steps.parse-request.outputs.arduinoLintLibraryManagerSetting }}
@@ -170,6 +171,7 @@ jobs:
           )"
           # Due to limitations of the GitHub Actions workflow system, dedicated outputs must be created for use in
           # certain workflow fields.
+          echo "::set-output name=conclusion::$(echo "$REQUEST" | jq -r -c '.conclusion')"
           echo "::set-output name=type::$(echo "$REQUEST" | jq -r -c '.type')"
           echo "::set-output name=error::$(echo "$REQUEST" | jq -r -c '.error')"
           echo "::set-output name=arduinoLintLibraryManagerSetting::$(echo "$REQUEST" | jq -r -c '.arduinoLintLibraryManagerSetting')"
@@ -195,10 +197,13 @@ jobs:
           labels: |
             - "topic: ${{ needs.parse.outputs.type }}"
 
+  # Handle problem found by the parser that can potentially be resolved by requester.
   parse-fail:
     needs:
       - parse
-    if: needs.parse.outputs.error != ''
+    if: >
+      needs.parse.outputs.conclusion != 'declined' &&
+      needs.parse.outputs.error != ''
 
     runs-on: ubuntu-latest
     steps:
@@ -223,13 +228,64 @@ jobs:
             More information:
             https://github.com/${{ github.repository }}/blob/main/README.md#if-the-problem-is-with-the-pull-request
 
+  # Requester's registry privileges have been revoked.
+  decline-request:
+    needs:
+      - parse
+    if: >
+      needs.parse.outputs.conclusion == 'declined' &&
+      needs.parse.outputs.error != ''
+    runs-on: ubuntu-latest
+    steps:
+      - name: Comment reason for declining request
+        uses: octokit/[email protected]
+        if: needs.parse.outputs.error != ''
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          route: POST /repos/{owner}/{repo}/issues/{issue_number}/comments
+          owner: ${{ github.repository_owner }}
+          repo: ${{ github.event.repository.name }}
+          issue_number: ${{ github.event.pull_request.number }}${{ github.event.issue.number }}
+          body: |
+            |
+            Hi @${{ github.actor }}
+            Your request has been declined:
+
+            ${{ env.ERROR_MESSAGE_PREFIX }}${{ needs.parse.outputs.error }}
+
+      - name: Close PR
+        uses: octokit/[email protected]
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          route: PATCH /repos/{owner}/{repo}/pulls/{pull_number}
+          owner: ${{ github.repository_owner }}
+          repo: ${{ github.event.repository.name }}
+          pull_number: ${{ github.event.pull_request.number }}${{ github.event.issue.number }}
+          state: closed
+
+      - name: Add conclusion label to PR
+        uses: octokit/[email protected]
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # See: https://docs.github.com/rest/issues/labels#add-labels-to-an-issue
+          route: POST /repos/{owner}/{repo}/issues/{issue_number}/labels
+          owner: ${{ github.repository_owner }}
+          repo: ${{ github.event.repository.name }}
+          issue_number: ${{ github.event.pull_request.number }}${{ github.event.issue.number }}
+          labels: |
+            - "conclusion: ${{ needs.parse.outputs.conclusion }}"
+
   check-submissions:
     name: Check ${{ matrix.submission.submissionURL }}
     needs:
       - parse
     if: >
       needs.parse.outputs.type == 'submission' ||
       needs.parse.outputs.type == 'modification'
+
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -279,6 +335,15 @@ jobs:
         if: matrix.submission.error != ''
         run: echo "PASS=false" >> "$GITHUB_ENV"
 
+      # Parser checks are relevant in the case where request is declined due to registry access having been revoked for
+      # the library repository owners. However, the rest of the checks are irrelevant and may result in confusing
+      # comments from the bot, so should be skipped.
+      - name: Skip the rest of the checks if request is declined
+        if: >
+          needs.parse.outputs.conclusion == 'declined' &&
+          env.PASS == 'true'
+        run: echo "PASS=false" >> "$GITHUB_ENV"
+
       - name: Install Arduino Lint
         if: env.PASS == 'true'
         run: |
@@ -422,12 +487,15 @@ jobs:
         run: |
           test -d "${{ env.CHECK_SUBMISSIONS_FAIL_FLAG_ARTIFACT_PATH }}"
 
+  # Handle problem found by the submission checks that can potentially be resolved by requester.
   check-submissions-fail:
     needs:
+      - parse
       - check-submissions-result
-    if: needs.check-submissions-result.outputs.pass == 'false'
+    if: >
+      needs.parse.outputs.conclusion != 'declined' &&
+      needs.check-submissions-result.outputs.pass == 'false'
     runs-on: ubuntu-latest
-
     steps:
       - name: Comment instructions to fix errors detected during submission checks
         uses: octokit/[email protected]
@@ -453,6 +521,37 @@ jobs:
             More information:
             https://github.com/${{ github.repository }}/blob/main/README.md#if-the-problem-is-with-the-pull-request
 
+  decline-submissions:
+    needs:
+      - parse
+      - check-submissions
+    if: needs.parse.outputs.conclusion == 'declined'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Close PR
+        uses: octokit/[email protected]
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          route: PATCH /repos/{owner}/{repo}/pulls/{pull_number}
+          owner: ${{ github.repository_owner }}
+          repo: ${{ github.event.repository.name }}
+          pull_number: ${{ github.event.pull_request.number }}${{ github.event.issue.number }}
+          state: closed
+
+      - name: Add conclusion label to PR
+        uses: octokit/[email protected]
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # See: https://docs.github.com/rest/issues/labels#add-labels-to-an-issue
+          route: POST /repos/{owner}/{repo}/issues/{issue_number}/labels
+          owner: ${{ github.repository_owner }}
+          repo: ${{ github.event.repository.name }}
+          issue_number: ${{ github.event.pull_request.number }}${{ github.event.issue.number }}
+          labels: |
+            - "conclusion: ${{ needs.parse.outputs.conclusion }}"
+
   merge:
     needs:
       - diff
@@ -605,6 +704,7 @@ jobs:
       - parse
     # These request types can't be automatically approved.
     if: >
+      needs.parse.outputs.conclusion != 'declined' &&
       needs.parse.outputs.type != 'submission' &&
       needs.parse.outputs.type != 'invalid'
     runs-on: ubuntu-latest
@@ -631,8 +731,10 @@ jobs:
     needs:
       # Run after all other jobs
       - parse-fail
+      - decline-request
       - merge-fail
       - check-submissions-fail
+      - decline-submissions
       - label
       - not-submission
     # Run if any job failed. The workflow is configured so that jobs only fail when there is an unexpected error.

FAQ.md

@@ -72,6 +72,8 @@ Follow the instructions [here](README.md#adding-a-library-to-library-manager).
 
 ### What are the requirements for a library to be added to Library Manager?
 
+- [ ] The library must be something of potential value to the Arduino community.
+- [ ] The submitter must behave in a responsible manner in their interactions with the Library Manager Registry.
 - [ ] The library must be fully compliant with the [Arduino Library Specification](https://arduino.github.io/arduino-cli/latest/library-specification).
 - [ ] The library must have [a library.properties file](https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata), in compliance with the Arduino Library 1.5 format.
 - [ ] The library.properties file must be located in the root of the repository.

README.md

@@ -33,6 +33,16 @@ See the instructions below for detailed instructions on how to do this via the G
 
 ### Instructions
 
+---
+
+⚠ If you behave irresponsibly in your interactions with this repository, your Library Manager Registry privileges will be revoked.
+
+Carefully read and follow the instructions in any comments the bot and human maintainers make on your pull requests. If you are having trouble following the instructions, add a comment that provides a detailed description of the problem you are having and a human maintainer will provide assistance.
+
+Although we have set up automation for the most basic tasks, this repository is maintained by humans. So behave in a manner appropriate for interacting with humans, including clearly communicating what you are hoping to accomplish.
+
+---
+
 1. You may want to first take a look at
    [the requirements for admission into the Arduino Library Manager index](FAQ.md#submission-requirements). Each submission will be checked for
    compliance before being accepted.