Mirroristas/openpgpjs
2
0
Fork 0
mirror of https://github.com/openpgpjs/openpgpjs.git synced 2025-11-26 15:35:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: address PR changes

Browse Source
This commit is contained in:
hulkoba 2024-01-11 14:08:17 +01:00
parent 43486c11df
commit 089abc0001
No known key found for this signature in database
GPG Key ID: ACB6C4A3A4F2BE2F
4 changed files with 31 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/ISSUE_TEMPLATE/BUG_REPORT.md vendored
View File

@ -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: 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 - 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 - 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! Thank you for your collaboration!

36
CONTRIBUTING.md
View File

@ -38,13 +38,13 @@ Please let us know you want to work on it so we can avoid multiple people workin
```bash ```bash
# Clone your fork of the repo into the current directory # 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 # Navigate to the newly cloned directory
cd <repo-name> cd openpgpjs
# Assign the original repo to a remote called "upstream" # 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: 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. 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 ## Coding conventions
@ -73,17 +73,9 @@ We ensure code consistency through our [ESLint config](https://github.com/openpg
## Commit conventions ## 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 Additionally, please try to follow the style of the commit messages on our [main branch](https://github.com/openpgpjs/openpgpjs/commits/main).
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).
## Testing ## 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. 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:**
Unit tests are handled by mocha and run inside node, you can run them using this command: To run the tests in Node.js, run `npm test`.
```sh
npm run test
```
**Browser Tests:** **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: 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** **Typescript definitions**
```sh When changing TypeScript definitions, update [the definitions.ts test file](https://github.com/openpgpjs/openpgpjs/blob/main/test/typescript/definitions.ts) accordingly.
npm run test-type-definitions Then, run `npm run test-type-definitions` to verify that it still type-checks.
``` (This is also automatically done for every PR.)
**Coverage** **Coverage**
We have good numbers but we could always use some help improving them! We have good numbers but we could always use some help improving them!
@ -139,9 +127,9 @@ npm run coverage
## Pull requests ## 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: 1. Update your branch to the latest changes in the upstream main branch, solving conflicts if any appear. You can do that locally with:

36
MAINTAINERS.md
View File

@ -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. 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. 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. 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 #### `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. 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. 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 #### 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 - 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 - 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 ##### 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. - **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. - **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. 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: 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. - **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 ### 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 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 ## Release process
@ -194,6 +192,6 @@ We keep it simple. We use npm’s `version` command as following:
npm version {major,minor,patch} 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). Additionally, we create a changelog in [GitHub releases](https://github.com/openpgpjs/openpgpjs/releases).