From 029d8ba759d3394c0f53bb15f3491fbf07a35e0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alba=20Herrer=C3=ADas?= Date: Wed, 13 Dec 2023 11:05:01 +0000 Subject: [PATCH 01/10] docs: add code of conduct --- CODE_OF_CONDUCT.md | 132 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..57aea031 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,132 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +contact@openpgpjs.org. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations From 5b5c2b611f42524842fadce331798ed7b26f4af3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alba=20Herrer=C3=ADas?= Date: Wed, 13 Dec 2023 11:05:56 +0000 Subject: [PATCH 02/10] docs: update bug report template --- .github/ISSUE_TEMPLATE/BUG_REPORT.md | 33 ++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/BUG_REPORT.md b/.github/ISSUE_TEMPLATE/BUG_REPORT.md index 25706937..39bf9676 100644 --- a/.github/ISSUE_TEMPLATE/BUG_REPORT.md +++ b/.github/ISSUE_TEMPLATE/BUG_REPORT.md @@ -2,9 +2,38 @@ name: Bug report about: Report an issue with this library --- - + + +**Expected behavior** + + +**Current behavior** + + +**Possible solution** + + +**Specifications** - OpenPGP.js version: - Affected platform (Browser or Node.js version): - \ No newline at end of file +**Description** + From 56a05e13d95eae5c782d2ed9bf796687135df244 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alba=20Herrer=C3=ADas?= Date: Wed, 13 Dec 2023 11:06:17 +0000 Subject: [PATCH 03/10] docs: add pull request template --- .github/PULL_REQUEST_TEMPLATE.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..c69eab3b --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,19 @@ + + +**Description:** + + +**Which issue(s) this PR fixes:** + +Fixes # + +**Breaking changes** + From da2989db4236b1b6bf5fe9e2892112ac2b605f38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alba=20Herrer=C3=ADas?= Date: Wed, 13 Dec 2023 11:08:35 +0000 Subject: [PATCH 04/10] docs: add contributing guide Co-Authored-By: Alex Feyerke <391124+espy@users.noreply.github.com> Co-Authored-By: Ayham Kteash <11707377+ayhamthemayhem@users.noreply.github.com> --- CONTRIBUTING.md | 192 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..0563a97c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,192 @@ +# Contributing to OpenPGP.js + +Please take a moment to review this document in order to make the contribution process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests. + +As for everything else in the project, the contributions are governed by our [Code of Conduct](https://github.com/openpgpjs/openpgpjs/blob/main/CODE_OF_CONDUCT.md). + +- [Contributing to OpenPGP.js](#contributing-to-openpgpjs) + - [Getting started](#getting-started) + - [Decide what you want to work on](#decide-what-you-want-to-work-on) + - [Notify your interest](#notify-your-interest) + - [Setting up the project in your local machine](#setting-up-the-project-in-your-local-machine) + - [Coding conventions](#coding-conventions) + - [Commit conventions](#commit-conventions) + - [Testing](#testing) + - [Pull requests](#pull-requests) + - [I have submitted my PR, what are the next steps?](#i-have-submitted-my-pr-what-are-the-next-steps) + - [Bug reports](#bug-reports) + - [Communication](#communication) + - [Thank you](#thank-you) + +## Getting started + +### Decide what you want to work on + +If you are looking for something to work on, we try to maintain a list of issues that should be suitable for first time contributions, they can be found tagged [`good-first-issue`](https://github.com/openpgpjs/openpgpjs/labels/good-first-issue). You can also look through our issues and pick some you like. If you're still unsure, please [reach out](#communication) and we would help you to the best of our abilities. + +### Notify your interest + +Please let us know you want to work on it so we can avoid multiple people working on the same issue. Ideally, notify us via our [Gitter](https://gitter.im/openpgpjs/openpgpjs), but expressing your interest in the issue itself is also ok. + +**Please ask first** before embarking on any significant pull request (e.g. implementing features, refactoring code), otherwise you risk spending a lot of time working on something that the project's developers might not want to merge into the project. + +### Setting up the project in your local machine + +1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the project, clone your fork, and configure the remotes: + + ```bash + # Clone your fork of the repo into the current directory + git clone https://github.com// + + # Navigate to the newly cloned directory + cd + + # Assign the original repo to a remote called "upstream" + git remote add upstream https://github.com/openpgpjs/ + ``` + +2. Install dependencies with your preferred package manager: + + ```bash + npm install + ``` + +3. Create a new topic branch (off the main project development branch) to contain your feature, change, or fix: + + ```bash + git checkout -b + ``` + +4. Follow our [coding conventions](#coding-conventions) while developing your changes. You can also run `npm run lint` to match our requirements. + +5. Write clear and meaningful git commit messages. Please follow our [commit message conventions](#commit-conventions) while committing to your branch. + +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. + +## Coding conventions + +We ensure code consistency through our [ESLint config](https://github.com/openpgpjs/openpgpjs/blob/main/.eslintrc.js). You can run `npm run lint` to lint your changes. When in doubt, follow the style of the surrounding code. + +## 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: + +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). + +## Testing + +We have multiple types of tests. They are located in the root [`/test`](https://github.com/openpgpjs/openpgpjs/tree/main/test) folder. +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 +``` + +**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: + +This will run the tests inside a browser environment: + +```sh + npm run browsertest +``` + +You can run the tests for multiple headless browsers using KarmaJs: + +` npm run test-browser` + +If you wanna start the tests using KarmaJs and BrowserStack: +`npm run test-browserstack` + +**_NOTE_**: You need to configure you env with `BROWSER_STACK_ACCESS_KEY` and `BROWSERSTACK_USERNAME` to be able to run the BrowserStack tests. + + +**Performance:** +To avoid performance regressions, we measure time and memory usage with the following testing suites (in `/benchmarks`): + +```sh +npm run benchmark-time +npm run benchmark-memory-usage +``` + +**Typescript definitions** + +```sh +npm run test-type-definitions +``` + +**Coverage** +We have good numbers but we could always use some help improving them! + +```sh +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. + +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. + +1. Update your branch to the latest changes in the upstream main branch, solving conflicts if any appear. You can do that locally with: + + ```bash + git pull --rebase upstream main + ``` + +2. Push your topic branch up to your fork: + + ```bash + git push origin + ``` + +3. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) with a clear title and follow the instructions specified in the Pull Request template. Include a detailed description explaining the reasons for the changes, making sure there is sufficient information for the reviewer to understand your changes. + +4. Check if the Github Actions workflows have passed. Address the errors if they have not. + +**IMPORTANT**: By submitting a patch, you agree to license your work under the same license as that used by the project. + +### I have submitted my PR, what are the next steps? + +First of all, thank you for your contribution! Sit back and relax. Someone from the team will review your PR and respond with comments as soon as possible (usually within a few weeks). Once you have addressed all the comments, your PR will be approved and merged. + +## Bug reports + +First things first: please **do not report security vulnerabilities in public issues!** Disclose responsibly following the instructions detailed in [SECURITY.md](https://github.com/openpgpjs/openpgpjs/blob/main/SECURITY.md). Thank you. + +A bug is a _demonstrable problem_ that is caused by the code in our repository. Good bug reports are extremely helpful! + +Guidelines for bug reports: + +1. **Use the GitHub issue search** — check if the issue has already been reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a reduced test case. + +A good bug report shouldn't leave others needing to chase you up for more information. Please try to be as detailed as possible in your report. What is your environment? What steps will reproduce the issue? What OS experiences the problem? What would you expect to be the outcome? All these details will help people to fix any potential bugs. + +To create a new bug report, go to Issues, and select the Bug Report template. + +## Communication + +Feel free to reach out! You can do so in our [Gitter](https://gitter.im/openpgpjs/openpgpjs) or in our [GitHub discussions](https://github.com/openpgpjs/openpgpjs/discussions) + +## Thank you + +Thanks to [Hoodie](https://github.com/hoodiehq/hoodie) for inspiring this contributing guide. From 21fcdc2ae8723b157cc82ea178d4f722fedd1a37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alba=20Herrer=C3=ADas?= Date: Wed, 13 Dec 2023 11:10:10 +0000 Subject: [PATCH 05/10] docs: add maintainers guide Co-Authored-By: Alex Feyerke <391124+espy@users.noreply.github.com> --- MAINTAINERS.md | 199 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 MAINTAINERS.md diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 00000000..59fe2698 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,199 @@ +# Maintainers Guide + +This document is intended for the active maintainers of the project. Its purpose is to help them offload knowledge and decision-making overhead into formalised processes, or a set of concrete suggestions. + +Maintainers, old and new, are encouraged to read and refer back to this guide whenever there are doubts about how to run the project, and also to record and additions and changes to project processes. + +**Project processes** +- [Issue Triage](#issue-triage) + - [Step 1: Type the Issue](#step-1-type-the-issue) + - [`Support` for support requests](#support-for-support-requests) + - [`Wontfix` for misplaced or irrelevant issues](#wontfix-for-misplaced-or-irrelevant-issues) + - [`Need more info` for incomplete issues](#need-more-info-for-incomplete-issues) + - [`Stale` for abandoned issues](#stale-for-abandoned-issues) + - [`Bug` for things that don’t work as intended](#bug-for-things-that-dont-work-as-intended) + - [Good First Issues and Help Wanted Issues](#good-first-issues-and-help-wanted-issues) + - [Criteria for a `Help wanted` Issue](#criteria-for-a-help-wanted-issue) + - [Criteria for a `Good first issue`](#criteria-for-a-good-first-issue) + - [Other Issue Types](#other-issue-types) + - [Step 2: Prioritize the Issue](#step-2-prioritize-the-issue) + - [`priority/critical-urgent`](#prioritycritical-urgent) + - [`priority/important-soon`](#priorityimportant-soon) + - [`priority/important-longterm`](#priorityimportant-longterm) + - [`priority/backlog`](#prioritybacklog) + - [Step 3: Assign the Work](#step-3-assign-the-work) + - [Step 4: Follow up](#step-4-follow-up) +- [Release process](#release-process) + + +## Issue Triage + +
+Source +The Issue Triage section of the guide was heavily inspired by and occasionally uses the excellent Kubernetes Contributors Guide. +
+ +**Maintainers are encouraged to regularly triage incoming issues and PRs**, which means: +- A short response to the issue author acknowledging that the issue was seen +- Evaluating and labelling the issue according to type, priority and urgency +- Assigning the issue/PR to a contributor or maintainer for work or review + +Triage can happen asynchronously and continuously, or in regularly scheduled meetings. + +**Benefits of triaging are:** +- Maintaining project momentum +- Engagement of contributors by increasing responsiveness +- Prevents piling up of issues and work +- Prevents issues and the project itself becoming stale +- Provides structure and an opportunity for collaborative decision-making with regards to the project trajectory and roadmap + +It can be beneficial to have triage be part of already existing regular meetings, and if the volume of incoming issues requires it, have a regular, public triage meeting. If there is a regular meeting, make sure it is added here and in the [CONTRIBUTING.md](/CONTRIBUTING.md). Also consider adding it to the [NEW-CONTRIBUTORS.md](/NEW-CONTRIBUTORS.MD) and explicitly invite new and prospective contributors to listen in or participate. This will give interested people a plannable, social opportunity to meet the maintainers and gain insight into the project, with both a low barrier to entry for the new contributors and a low amount of additional effort for the maintainers. + +### Step 1: Type the Issue + +Issues can be of various types, some of which have labels: + +#### `Support` for support requests + +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 + +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 realise that the question is a duplicate of an existing discussion, and you can easily find that discussion, it’s worth linking to the existing one instead of creating a new one. + +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. + +#### `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. + +If you can, close the issue with a comment that points the poster to the correct repo. + +#### `Need more info` for incomplete issues + +These are issues that seem worthwhile, but are not yet actionable. Give it the `Need more info` label and prod the author for that info. + +#### `Stale` for abandoned issues + +These are usually `Need more info` issues where the original author does not respond within a sensible time frame (say, a month. People are busy). These are good candidates for a Github bot to manage for you. + +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: + +- 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. + +- **Up-To-Date:** Often these issues become obsolete and have already been completed, are no longer desired, no longer make sense, or have changed priority or difficulty. + +##### Criteria for a `Good first issue` + +Items marked with the `Good first issue` label are intended for first-time contributors. It indicates that maintainers will _proactively_ keep an eye out for the corresponding pull requests and shepherd them along. + +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. + +- **Solution Explained:** The recommended solution is clearly described in the issue. There are acceptance criteria defined in the issue. + +- **Provides Context:** If background knowledge is required, this should be explicitly mentioned and a list of suggested readings included. + +- **Gives Examples:** If possible, link to examples of similar implementations so new contributors have a reference guide for their changes. + +- **Identifies Relevant Code:** The relevant code and tests to be changed should be linked in the issue. + +- **Ready to Test:** There should be existing tests that can be modified, or existing test cases fit to be copied. If the area of code doesn't have tests, before labeling the issue, add a test fixture. This prep often makes a great help wanted task! + +Maintainers are encouraged to invest the extra effort to write and shepherd along these issues and PRs, since onboarding reliable, long-term contributors is an excellent foundation for a sustainable, long-running project that doesn’t burn out the participants. + +**Measures can include:** +- Help with the contributor’s dev setup, and if you realise that the onboarding documentation for developers is lacking or out of date, assign their improvement to the new contributor! They probably took notes on the process anyway. +- Proactively watch open first timer-PRs as they change and get in touch if you can save people some time or pain. +- Invite them to meetings and chats +- Rope in other maintainers for a second LGTM at the end +- If the contributor agrees, publicly thank them on whichever channels you broadcast on, as well as in the release notes +- Suggest related `Help wanted` issues + +Unless the contributors are insecure about public communication, you’re encouraged to _not_ use private messages as much as possible. Keeping communication public ensures that other people can find and benefit from your discussions in the future. + +#### Other Issue Types + +There are a variety of additonal labels that are generally self-explanatory, for example: + +- `Feature` +- `Documentation` +- `Performance` +- `Testing` +- `Cleanup` +- `Security` +- `Compatibility` + +A full list can always be found on the project’s [labels page](https://github.com/openpgpjs/openpgpjs/labels). + +### Step 2: Prioritize the Issue + +Aside from a type label and the housekeeping labels, issues that are or should become actionable also benefit from having a priority label. + +#### `priority/critical-urgent` + +Something has gone 💥. Stuff is on fire. Drop what you’re doing and work on this next. Must be in the next planned release, or requires its own release. + +#### `priority/important-soon` + +Must be staffed and worked on either currently or very soon—ideally in time for the next release. Important, but wouldn't block a release. + +#### `priority/important-longterm` + +Important over the long term, but may not be currently staffed and/or may require multiple releases to complete. Wouldn't block a release. + +#### `priority/backlog` + +Would be nice, but no one has the resources to work on it. Good candidates for the `Help wanted` label. + +### Step 3: Assign the Work + +It should be clear who is responsible for working on an issue once it has been triaged and deemed actionable. This also includes eventual reviews. Ideally don’t assign things to people who aren’t expecting it. + +### 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. + +## Release process + +We keep it simple. We use npm’s `version` command as following: + +```sh +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. + +Additionally, we create a changelog in [GitHub releases](https://github.com/openpgpjs/openpgpjs/releases). From 436b87d89ba7899fe911539442bb8a4d1b7837b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alba=20Herrer=C3=ADas?= Date: Wed, 13 Dec 2023 11:10:53 +0000 Subject: [PATCH 06/10] docs: add new contributors guide Co-Authored-By: Alex Feyerke <391124+espy@users.noreply.github.com> --- NEW-CONTRIBUTORS.MD | 91 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 NEW-CONTRIBUTORS.MD diff --git a/NEW-CONTRIBUTORS.MD b/NEW-CONTRIBUTORS.MD new file mode 100644 index 00000000..554520b1 --- /dev/null +++ b/NEW-CONTRIBUTORS.MD @@ -0,0 +1,91 @@ +# Guide for New Contributors + +👋 **First off! Hello, and a warm welcome to the OpenPGP.js project!** + +We’re delighted that you’re interested in participating, and we want to make it as pleasant and simple as we can, whether you want to send a one-off pull request or you want to become part of the team in the long run. + +**If you’re new here and interested in any form of contribution, this guide is for you.** + +**Contents:** + +- [Who are we and what is OpenPGP.js?](#who-are-we-and-what-is-openpgpjs) +- [Who can Contribute?](#who-can-contribute) +- [How do you get Started?](#how-do-you-get-started) + - [Get Familiar with the Basic Principles](#get-familiar-with-the-basic-principles) + - [Take OpenPGP.js for a Spin](#take-openpgpjs-for-a-spin) + - [Getting your Bearings in the OpenPGP.js Project](#getting-your-bearings-in-the-openpgpjs-project) + +## Who are we and what is OpenPGP.js? + +[OpenPGP.js](https://openpgpjs.org/) is a JavaScript implementation of the [OpenPGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) protocol. It implements [RFC4880](https://tools.ietf.org/html/rfc4880) and parts of [RFC4880bis](https://tools.ietf.org/html/draft-ietf-openpgp-rfc4880bis-10). + +This project aims to provide an Open Source OpenPGP library in JavaScript so it can be used on virtually every device. Instead of other implementations that are aimed at using native code, OpenPGP.js is meant to bypass this requirement (i.e. people will not have to install gpg on their machines in order to use the library). The idea is to implement all the needed OpenPGP functionality in a JavaScript library that can be reused in other projects that provide browser extensions or server applications. It should allow you to sign, encrypt, decrypt, and verify any kind of text - in particular e-mails - as well as managing keys. + +This project is maintained by [Proton Mail](https://proton.me/blog/openpgpjs-email-encryption) and is supported by the EU’s Horizon 2020 programme. + +OpenPGP.js is built by [a variety of people](https://github.com/orgs/openpgpjs/people), but there are a couple you’ll run into more frequently, and who can be considered the core of the project: + +- [twiss](https://github.com/twiss) (Daniel Huigens) +- [larabr](https://github.com/larabr) + +## Who can Contribute? + +While this _is_ cryptography-heavy JavaScript software, and those skills are especially relevant, an Open Source project such as this one has a wide range of needs, and there are a lot of opportunities to help: + +- There are usually some non-cryptography related JS (and TS!) tasks +- You can expand or improve the test suite +- You can take the project for a test drive and update the dev setup documentation for your platform (see [CONTRIBUTING.md](/CONTRIBUTING.md)) +- You can improve the various documentation resources in general, for example by looking for [documentation issues](https://github.com/openpgpjs/openpgpjs/issues?q=is%3Aissue+is%3Aopen+label%3ADocumentation), or just picking something to expand upon, edit or check for typos +- You can improve the build process +- You can do manual tests and UI/UX evaluations of features or tools and help improve their usability +- You can improve or maintain [our website](https://openpgpjs.org/) +- You can evangelize for the project: present or talk about OpenPGP.js in your company, local tech meetup, youtube channel, or similar circles +- You can answer questions on our [Gitter](https://gitter.im/openpgpjs/openpgpjs) or our [GitHub discussions](https://github.com/openpgpjs/openpgpjs/discussions) + +## How do you get Started? + +### Get Familiar with the Basic Principles + +Depending on your background and contribution to the project, it might be useful to read up on the basics of how online cryptography and PGP work: + +- [A quick intro to PGP](https://proton.me/blog/what-is-pgp-encryption), covering public and private keys, symmetric and asymmetric keys, signatures and address verification. This article is by ProtonMail, [the primary maintainers of this project](https://proton.me/blog/openpgpjs-email-encryption). +- A more general [video](https://www.youtube.com/watch?v=NuyzuNBFWxQ) on the basic cryptographic principles frequently used online, such as hashing, salting, encryption, symmetric and asymmetric keys, and signing. + +### Take OpenPGP.js for a Spin + +This involves getting things running on your machine and trying out the features. Thankfully, OpenPGP.js doesn’t have a lot of prerequisites: + +1. You need a [current version of node.js](https://nodejs.org/en/about/previous-releases) installed +2. Install depencencies with `$ npm i` + +That’s it. Now you can run the node tests: + +```bash +npm test +``` + +You can also run the tests in a browser with: + +```bash +npm run browsertest +``` + +And that’s your dev environment sorted. + +### Getting your Bearings in the OpenPGP.js Project + +We’ve got a bunch of helpful resources you might be interested in: + +- There’s a [public gitter chat](https://app.gitter.im/#/room/#openpgpjs_openpgpjs:gitter.im), which is a good place for establishing first contact with the project +- **Our [Guide for Contributors](/CONTRIBUTING.md), which details topics such as project processes, code and commit conventions, expectations for PRs, as well as documentation on dev setup and testing.** +- The [Code of Conduct](/CODE_OF_CONDUCT.md) we operate by, and which you are also expected to adhere to + +And of course our [GitHub issues](https://github.com/openpgpjs/openpgpjs/issues), where you can find tasks to take on. We try to have some [Good First Issues](https://github.com/openpgpjs/openpgpjs/labels/good%20first%20issue) for newcomers in place, but there might not always be some available. + +In any case, it’s always a good idea to [have a chat with us](https://app.gitter.im/#/room/#openpgpjs_openpgpjs:gitter.im) before you start any work. + +All that’s left here is to thank you for your time and interest, and we hope you’ll join us on our quest for better Open Source cryptography on the web! 🚀 + +👋 + + From 43486c11df6789b2b1c631981271c4ef6cb26450 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alba=20Herrer=C3=ADas?= Date: Wed, 13 Dec 2023 12:30:45 +0000 Subject: [PATCH 07/10] docs: update readme --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 72e5bf2f..71da7c78 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ OpenPGP.js [![BrowserStack Status](https://automate.browserstack.com/badge.svg?b - [Security recommendations](#security-recommendations) - [Development](#development) - [How do I get involved?](#how-do-i-get-involved) + - [Code of conduct](#code-of-conduct) - [License](#license) ### Platform Support @@ -674,7 +675,11 @@ For debugging browser errors, you can run `npm start` and open [`http://localhos ### How do I get involved? -You want to help, great! It's probably best to send us a message on [Gitter](https://gitter.im/openpgpjs/openpgpjs) before you start your undertaking, to make sure nobody else is working on it, and so we can discuss the best course of action. Other than that, just go ahead and fork our repo, make your changes and send us a pull request! :) +You want to help, great! We have two guides for you to read: [our guide for new contributors](https://github.com/openpgpjs/openpgpjs/blob/main/NEW-CONTRIBUTORS.md), and afterwards you can take a look at our general [contributing](https://github.com/openpgpjs/openpgpjs/blob/main/CONTRIBUTING.md) guide. If you have questions, don't hesitate to write us on [Gitter](https://gitter.im/openpgpjs/openpgpjs) :) + +### Code of conduct + +The contributions are governed by our [Code of Conduct](https://github.com/openpgpjs/openpgpjs/blob/main/CODE_OF_CONDUCT.md). ### License From 089abc0001d723c1c8fff1bff46cf67c086c5bb7 Mon Sep 17 00:00:00 2001 From: hulkoba Date: Thu, 11 Jan 2024 14:08:17 +0100 Subject: [PATCH 08/10] 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:** - + **Which issue(s) this PR fixes:**