Merge df7f6748aa8b081393acbf913bd3c12c66d94876 into 884c6f4f3d73f40ca0057733d8d86b7ffcdf1d46

.github/ISSUE_TEMPLATE/BUG_REPORT.md

@@ -2,9 +2,38 @@
 name: Bug report
 about: Report an issue with this library
 ---
-<!-- Please search existing issues and discussions to avoid creating duplicates. -->
+<!--
+
+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
+- 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! 
+
+-->
+
+**Expected behavior**
+<!--- Tell us what should happen -->
+
+**Current behavior**
+<!--- Tell us what happens instead of the expected behavior -->
+
+**Possible solution** 
+<!--- Not obligatory, but suggest a fix/reason for the bug -->
+
+**Specifications**
 
 - OpenPGP.js version:
 - Affected platform (Browser or Node.js version):
 
-<!-- Describe the bug you have encountered -->
+**Description**
+<!-- 
+
+Describe the bug you have encountered in detail. If suitable, include:
+- Code snippets (so we can reproduce it). As minimal and precisely as possible. Please put these in appropriate code fences for better readability.
+- Steps required to reproduce the bug 
+- The error stack 
+
+Also include any other information you want to share that is relevant to the issue being reported.
+-->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+<!--  Thank you for sending a pull request! Please take a moment to review the following:
+
+- If this is your first contribution, please read our guide for new contributors https://github.com/openpgpjs/openpgpjs/blob/main/NEW-CONTRIBUTORS.md and our general contributing guide https://github.com/openpgpjs/openpgpjs/blob/main/CONTRIBUTING.md
+- Make sure that you have added or run the appropriate tests https://github.com/openpgpjs/openpgpjs/blob/main/CONTRIBUTING.md#testing
+- If your PR is not finished, please mark it as a draft
+-->
+
+**Description:**
+<!-- Explain what this PR does and why we need it -->
+
+**Which issue(s) this PR fixes:**
+<!--
+*Automatically closes linked issue when PR is merged.
+Usage: `Fixes #<issue number>`, or `Fixes (paste link of issue)`.
+-->
+Fixes #
+
+**Breaking changes**
+<!-- Does this PR introduce any breaking changes? If so, list which ones -->

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

CONTRIBUTING.md

@@ -0,0 +1,156 @@
+# 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/<your-username>/openpgpjs
+
+   # Navigate to the newly cloned directory
+   cd openpgpjs
+
+   # Assign the original repo to a remote called "upstream"
+   git remote add upstream https://github.com/openpgpjs/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 <topic-branch-name>
+   ```
+
+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, when appropriate.
+
+## 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 roughly follow the Git commit guidelines in [this blog post](https://cbea.ms/git-commit/).
+
+Additionally, please try to follow the style of the commit messages on our [main branch](https://github.com/openpgpjs/openpgpjs/commits/main).
+
+## Testing
+
+Tests. They are located in the root [`/test`](https://github.com/openpgpjs/openpgpjs/tree/main/test) folder.
+Before running the tests, run `npm run build` to build OpenPGP.js if you've made changes since running `npm install`.
+
+**Unit Tests:**
+To run the tests in Node.js, run `npm test`.
+
+To run the tests in a browser, run `npm run browsertest`.
+
+
+**Typescript 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!
+
+```sh
+npm run coverage
+```
+
+## Pull requests
+
+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 🙂 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:
+
+   ```bash
+   git pull --rebase upstream main
+   ```
+
+2. Push your topic branch up to your fork:
+
+   ```bash
+   git push origin <topic-branch-name>
+   ```
+
+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** &mdash; check if the issue has already been reported.
+
+2. **Check if the issue has been fixed** &mdash; try to reproduce it using the latest `main` branch in the repository.
+
+3. **Isolate the problem** &mdash; 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.

MAINTAINERS.md

@@ -0,0 +1,170 @@
+# Maintainers Guide <!-- omit in toc -->
+
+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
+
+<details>
+<summary>Source</summary>
+The Issue Triage section of the guide was heavily inspired by and occasionally uses the excellent <a href="https://github.com/kubernetes/community/blob/master/contributors/guide/issue-triage.md">Kubernetes Contributors Guide</a>.
+</details>
+
+**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
+
+
+### 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.
+
+#### `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.
+
+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.
+
+#### Good First Issues and Help Wanted Issues
+
+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 the core maintainers won't have time for it and would welcome external contributors.
+
+##### Criteria for a `Help wanted` Issue
+
+- **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.
+
+
+##### 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.
+
+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: Follow up
+
+**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
+
+We keep it simple. We use npm’s `version` command as following:
+
+```sh
+npm version {major,minor,patch}
+```
+
+(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).

NEW-CONTRIBUTORS.MD

@@ -0,0 +1,91 @@
+# Guide for New Contributors <!-- omit from toc -->
+
+👋 **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! 🚀
+
+👋
+
+

README.md

@@ -30,6 +30,7 @@ OpenPGP.js [![Join the chat on Gitter](https://badges.gitter.im/Join%20Chat.svg)
     - [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
@@ -681,7 +682,11 @@ For debugging browser errors, run the following command:
 
 ### 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