From 089abc0001d723c1c8fff1bff46cf67c086c5bb7 Mon Sep 17 00:00:00 2001
From: hulkoba <jacoba@neighbourhood.ie>
Date: Thu, 11 Jan 2024 14:08:17 +0100
Subject: [PATCH] docs: address PR changes

---
 .github/ISSUE_TEMPLATE/BUG_REPORT.md |  2 +-
 .github/PULL_REQUEST_TEMPLATE.md     |  2 +-
 CONTRIBUTING.md                      | 36 ++++++++++------------------
 MAINTAINERS.md                       | 36 +++++++++++++---------------
 4 files changed, 31 insertions(+), 45 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/BUG_REPORT.md b/.github/ISSUE_TEMPLATE/BUG_REPORT.md
index 39bf9676..a17d4c3d 100644
--- a/.github/ISSUE_TEMPLATE/BUG_REPORT.md
+++ b/.github/ISSUE_TEMPLATE/BUG_REPORT.md
@@ -6,7 +6,7 @@ about: Report an issue with this library
 
 Before creating a new bug report, please take a few moments to review the following:
 - Have you searched existing issues and discussions about your problem? Your problem might be already solved, and this could avoid creating duplicates
-- Is this a security related bug? If so, disclose it privately following the procedure described in https://github.com/openpgpjs/openpgpjs/blob/main/SECURITY.md
+- Could this issue cause a security vulnerability? If so, please disclose it privately following the procedure described in https://github.com/openpgpjs/openpgpjs/blob/main/SECURITY.md
 - Is this an implementation or support question? If so, open a discussion here https://github.com/openpgpjs/openpgpjs/discussions/categories/q-a 
 
 Thank you for your collaboration! 
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index c69eab3b..fadd9b95 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -6,7 +6,7 @@
 -->
 
 **Description:**
-<!-- Explain what this PR does and why we need it  -->
+<!-- Explain what this PR does and why we need it -->
 
 **Which issue(s) this PR fixes:**
 <!--
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0563a97c..0d7c6eb5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -38,13 +38,13 @@ Please let us know you want to work on it so we can avoid multiple people workin
 
    ```bash
    # Clone your fork of the repo into the current directory
-   git clone https://github.com/<your-username>/<repo-name>
+   git clone https://github.com/<your-username>/openpgpjs
 
    # Navigate to the newly cloned directory
-   cd <repo-name>
+   cd openpgpjs
 
    # Assign the original repo to a remote called "upstream"
-   git remote add upstream https://github.com/openpgpjs/<repo-name>
+   git remote add upstream https://github.com/openpgpjs/openpgpjs
    ```
 
 2. Install dependencies with your preferred package manager:
@@ -65,7 +65,7 @@ Please let us know you want to work on it so we can avoid multiple people workin
 
 6. Make sure to update or add to the tests when appropriate. Run the appropriate testing suites to check that all tests pass after you've made changes. You can read about our different types of tests in our [Testing](#testing) section.
 
-7. If you added or changed a feature, make sure to document it accordingly in the [README.md](https://github.com/openpgpjs/openpgpjs/blob/main/README.md) file.
+7. If you added or changed a feature, make sure to document it accordingly in the [README.md](https://github.com/openpgpjs/openpgpjs/blob/main/README.md) file, when appropriate.
 
 ## Coding conventions
 
@@ -73,17 +73,9 @@ We ensure code consistency through our [ESLint config](https://github.com/openpg
 
 ## Commit conventions
 
-We follow the seven rules of a great Git commit message, which is extensively described in [this blog post](https://cbea.ms/git-commit/), but in short the principles are:
+We roughly follow the Git commit guidelines in [this blog post](https://cbea.ms/git-commit/).
 
-1. Separate subject from body with a blank line
-2. Limit the subject line to 50 characters
-3. Capitalize the subject line
-4. Do not end the subject line with a period
-5. Use the imperative mood in the subject line
-6. Wrap the body at 72 characters
-7. Use the body to explain what and why vs. how
-
-You can also take a look at our [main branch commits](https://github.com/openpgpjs/openpgpjs/commits/main).
+Additionally, please try to follow the style of the commit messages on our [main branch](https://github.com/openpgpjs/openpgpjs/commits/main).
 
 ## Testing
 
@@ -91,11 +83,7 @@ We have multiple types of tests. They are located in the root [`/test`](https://
 Before you can run the tests you need to build the project using `npm run build` and this will bundle the project and the tests for it be used in our different testing environments.
 
 **Unit Tests:**
-Unit tests are handled by mocha and run inside node, you can run them using this command:
-
-```sh
-npm run test
-```
+To run the tests in Node.js, run `npm test`.
 
 **Browser Tests:**
 For debugging browser errors, you can run `npm start` and open [`http://localhost:8080/test/unittests.html`](http://localhost:8080/test/unittests.html) in a browser, or run one the following commands:
@@ -126,9 +114,9 @@ npm run benchmark-memory-usage
 
 **Typescript definitions**
 
-```sh
-npm run test-type-definitions
-```
+When changing TypeScript definitions, update [the definitions.ts test file](https://github.com/openpgpjs/openpgpjs/blob/main/test/typescript/definitions.ts) accordingly.
+Then, run `npm run test-type-definitions` to verify that it still type-checks.
+(This is also automatically done for every PR.)
 
 **Coverage**
 We have good numbers but we could always use some help improving them!
@@ -139,9 +127,9 @@ npm run coverage
 
 ## Pull requests
 
-Good pull requests - patches, improvements, new features - are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.
+Good pull requests - patches, improvements, new features - are sa fantastic help. They should remain focused in scope and avoid containing unrelated commits.
 
-If you have never created a pull request before, welcome :smile: [Here is a great tutorial](https://app.egghead.io/playlists/how-to-contribute-to-an-open-source-project-on-github) on how to create a pull request.
+If you have never created a pull request before, welcome 🙂 Read the GitHub docs on [how to create a pull request from a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
 
 1. Update your branch to the latest changes in the upstream main branch, solving conflicts if any appear. You can do that locally with:
 
diff --git a/MAINTAINERS.md b/MAINTAINERS.md
index 59fe2698..c2347ada 100644
--- a/MAINTAINERS.md
+++ b/MAINTAINERS.md
@@ -57,7 +57,7 @@ Issues can be of various types, some of which have labels:
 
 Support requests, eg. issues that are not bugs and exclusively concern the usage of the code as it is, will be converted in to a discussion and closed.
 
-Here is [an example](https://github.com/openpgpjs/openpgpjs/issues/1661) of this occuring
+Here is [an example](https://github.com/openpgpjs/openpgpjs/issues/1661) of this occuring.
 
 If you find yourself doing this a lot, your `.github/ISSUE_TEMPLATE` needs improvement. The template should be effectively guiding people in need of support to the discussions and away from the issues.
 
@@ -65,6 +65,17 @@ If you realise that the question is a duplicate of an existing discussion, and y
 
 If questions are frequently asked, they might be a frequently asked question! Consider adding the solution to the documentation, Wiki or FAQ, whichever applies and is easily discoverable.
 
+#### `Bug` for things that don’t work as intended
+
+1. Assuming this is not or no longer a `Need more info` issue, attempt to reproduce the bug
+   1. Search for duplicates, if one exists, point the current issue there, and close the new one
+   2. If you can reproduce it and there are no duplicates, prioritize it and add the `Bug` label
+      1. If you need more info before this issue becomes actionable despite being able to reproduce it, prod the author and add a `Need more info` label
+   3. If you can’t reproduce it, contact the author with the reason, and add a `Need more info` to the `Bug` label
+      1. If the issue cannot be reproduced by anyone other than the author, agree with them that the issue should be closed
+
+As with regular `Need more info` issues, `Need more info` + `Bug` issues are also subject to the [Abandoned/Stale](#abandonedstale) rule above, and should be closed after a set period of time.
+
 #### `Wontfix` for misplaced or irrelevant issues
 
 These are issues that pertain to other projects but have landed here, usually because the poster has no insight into the source of the issue, and the source is actually a dependency.
@@ -81,28 +92,17 @@ These are usually `Need more info` issues where the original author does not res
 
 Here’s [an example](https://github.com/openpgpjs/openpgpjs/issues/883) of an issue that was manually closed after the author not responding for a year.
 
-#### `Bug` for things that don’t work as intended
-
-1. Assuming this is not or no longer a `Need more info` issue, attempt to reproduce the bug
-   1. Search for duplicates, if one exists, point the current issue there, and close the new one
-   2. If you can reproduce it and there are no duplicates, prioritize it and add the `Bug` label
-      1. If you need more info before this issue becomes actionable despite being able to reproduce it, prod the author and add a `Need more info` label
-   3. If you can’t reproduce it, contact the author with the reason, and add a `Need more info` to the `Bug` label
-      1. If the issue cannot be reproduced by anyone other than the author, agree with them that the issue should be closed
-
-As with regular `Need more info` issues, `Need more info` + `Bug` issues are also subject to the [Abandoned/Stale](#abandonedstale) rule above, and should be closed after a set period of time.
-
 #### Good First Issues and Help Wanted Issues
 
-To identify issues that are specifically groomed for new contributors, we use the `Help wanted` _and_ `Good first issue` labels. As to the difference between the two:
+To identify issues that are specifically groomed for new contributors, we use the `Good first issue` label.
+
+As to the difference between `Help wanted` and `Good first issue`:
 
 - a `Good first issue` always also implies `Help wanted` from outside the project
 - but `Help wanted` does not necessarily mean it’s a `Good first issue`. Might be really tricky but none of the current maintainers has the resources to tackle it
 
 ##### Criteria for a `Help wanted` Issue
 
-- **Low Barrier to Entry:** It should be easy for new contributors. Documentation on how that type of change should be made should already exist.
-
 - **Clear Task:** The task is agreed upon and does not require further discussions in the community. Call out if that area of code is untested and requires new fixtures.
 
 - **Goldilocks priority:** The priority should not be so high that a core contributor should do it, but not too low that it isn't useful enough for a core contributor to spend time reviewing it, answering questions, helping get it into a release, etc.
@@ -115,8 +115,6 @@ Items marked with the `Good first issue` label are intended for first-time contr
 
 New contributors should not be left to find an approver, ping for reviews, or identify that their build failed due to a flake. It is important to make new contributors feel welcome and valued. We should assure them that they will have an extra level of help with their first contribution.
 
-After a contributor has successfully completed one or two `Good first issue` items, they should be ready to move on to `Help wanted` items.
-
 All `Good first issue` items need to follow the guidelines for help wanted items in addition to meeting the following criteria:
 
 - **No Barrier to Entry:** The task is something that a new contributor can tackle without advanced setup or domain knowledge. This often means improving documentation, tests or working on small, peripheral, testable bugs or features. Tasks that are similar to work that has already been completed are good candidates.
@@ -184,7 +182,7 @@ It should be clear who is responsible for working on an issue once it has been t
 ### Step 4: Follow up
 
 - **If no PR is opened on an issue within a month**, a maintainer should contact the assignee and ask them to create a PR or unassign themselves
-- **If a PR is ready for review**, use your triage meeting to find someone to review it within a reasonable amount of time. If you cannot manage a review soon, explain that to the contributor so they’re not left hanging and know what to expect.
+- **If a PR is ready for review**, find someone to review it within a reasonable amount of time. If you cannot manage a review soon, explain that to the contributor so they’re not left hanging and know what to expect.
 
 ## Release process
 
@@ -194,6 +192,6 @@ We keep it simple. We use npm’s `version` command as following:
 npm version {major,minor,patch}
 ```
 
-Which will trigger the `preversion`, `version` and `postversion` scripts specified in the `package.json`. These will handle the testing, building, publish to npm and pushing to GitHub. 
+(Depending on whether a major, minor or patch release is to be created.) This command will run tests, create a build, publish it to npm, and push to GitHub. 
 
 Additionally, we create a changelog in [GitHub releases](https://github.com/openpgpjs/openpgpjs/releases).