docs: add CONTRIBUTING.md, SECURITY.md and update doc/reference.md (#181)

1 files changed, 117 insertions, 0 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..2d83d73b
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,117 @@
+- [Contribution policy](#contribution-policy)
+- [Adding a new package](#adding-a-new-package)
+    - [The anatomy of a package](#the-anatomy-of-a-package)
+    - [Package name](#package-name)
+    - [Package homepage](#package-homepage)
+    - [Package categories](#package-categories)
+    - [Package languages](#package-languages)
+    - [Package installer](#package-installer)
+- [Code style](#code-style)
+- [Generated code](#generated-code)
+
+# Contribution policy
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT
+RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14][bcp14]
+[RFC2119][rfc2119] [RFC8174][rfc8174] when, and only when, they appear in all capitals, as shown here.
+
+[bcp14]: https://tools.ietf.org/html/bcp14
+[rfc2119]: https://tools.ietf.org/html/rfc2119
+[rfc8174]: https://tools.ietf.org/html/rfc8174
+
+# Adding a new package
+
+Package definitions reside within the `lua/mason-registry` directory. Each package MUST reside in its own directory with
+a main entrypoint file `init.lua`. The name of the directory MUST be the same as the package name. The `init.lua` file
+MUST return a `Package` (`mason-core.package`) instance.
+
+## The anatomy of a package
+
+Each package consists of a specification ([`PackageSpec`](https://github.com/williamboman/mason.nvim/blob/main/doc/reference.md#packagespec)), describing metadata about
+the package as well as its installation instructions. The [`Package`](https://github.com/williamboman/mason.nvim/blob/main/doc/reference#package) class encapsulates a
+specification and provides utility methods such as `Package:install()` and `Package:check_new_version({callback})`.
+
+### Package name
+
+The name of a package MUST follow the following naming scheme:
+
+1. If the upstream package name is sufficiently unambiguous, or otherwise widely recognized, that name MUST be used
+1. If the upstream package provides a single executable with a name that is sufficiently unambiguous, or otherwise
+   widely recognized, the name of the executable MUST be used
+1. If either the package or executable name is ambiguous, a name where a clarifying prefix or suffix is added SHOULD be
+   used
+1. As a last resort, the name of the package should be constructed to best convey its target language and scope, e.g.
+   `json-lsp` for a JSON language server.
+
+### Package homepage
+
+A package MUST have a homepage associated with it. The homepage SHOULD be a URL to the landing page of a public website.
+If no public website exists, the homepage MUST be a URL to the source code of the package (e.g. a GitHub repository).
+
+### Package categories
+
+See: [`Package.Cat`](https://github.com/williamboman/mason.nvim/blob/main/doc/reference.md#packagecat)
+
+A package SHOULD belong to one or more categories. Should no category apply, it is a sign that the package's scope
+exceeds that of mason.nvim.
+
+### Package languages
+
+See: [`Package.Lang`](https://github.com/williamboman/mason.nvim/blob/main/doc/reference.md#packagelang)
+
+A package SHOULD belong to one or more languages. There are however situations where no languages apply, in which case
+no languages should be applied.
+
+### Package installer
+
+A package installer MUST be a function. It MAY be an asynchronous function that MUST use the `mason-core.async`
+implementation. The installer function will be invoked by mason when the package is requested to be installed. It will
+be invoked with a single argument of type
+[`InstallContext`](https://github.com/williamboman/mason.nvim/blob/main/doc/reference.md#installcontext). The parameter
+name of the function MUST be `ctx` (abbreviation of context).
+
+Package installers SHOULD make use of the [built-in
+managers](https://github.com/williamboman/mason.nvim/tree/main/lua/mason-core/managers), which provide a high-level API
+for common installation instructions.
+
+A package installer MUST provide a "primary source" describing how, and where, the package was installed from. This is
+done via the `InstallContext` API (`ctx.receipt:with_primary_source({source})`) or via some other API provided by a
+manager. The provided `{source}` MUST be a table with a field `type` that MUST be supported by mason (e.g. `"npm"`,
+`"pip3"`).
+
+# Code style
+
+This project adheres to Editorconfig as well as Stylua formatting rules. New patches MUST adhere to these coding styles.
+
+# Generated code
+
+Some changes such as adding or changing a package defintion will require generating some new code. This can be done on
+Unix systems like so:
+
+```sh
+$ make generate
+```
+
+# Tests
+
+[Tests](https://github.com/williamboman/mason.nvim/tree/main/tests) MAY be added or modified to reflect any new changes.
+Tests can be executed on Unix systems like so:
+
+```sh
+$ make test
+$ FILE=tests/mason-core/managers/luarocks_spec.lua make test
+````
+
+# Adding or changing a feature
+
+Adding or changing a feature MUST be preceeded with an issue where scope and acceptance criteria are agreed upon with
+project maintainers before implementation.
+
+# Commit style
+
+Commits SHOULD follow the [conventional commits guidelines](https://www.conventionalcommits.org/en/v1.0.0/).
+
+# Pull requests
+
+Once a pull request is marked as ready for review (i.e. not in draft mode), new changes SHOULD NOT be force-pushed to
+the branch. Merge commits SHOULD be preferred over rebases.