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

3 files changed, 232 insertions, 1 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.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 00000000..0ad35d3b
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,7 @@
+# Security policy
+
+## Reporting a Vulnerability
+
+Please report any suspected security vulnerabilities to **william@redwill.se**. You will receive a response from me
+within 48 hours. If the issue is confirmed, we will release a patch as soon as possible depending on complexity. Please
+follow [responsible disclosure practices](https://en.wikipedia.org/wiki/Coordinated_vulnerability_disclosure). Thanks!
diff --git a/doc/reference.md b/doc/reference.md
index ad807436..25496863 100644
--- a/doc/reference.md
+++ b/doc/reference.md
@@ -25,6 +25,14 @@ something is missing or if something could be improved!
     -   [`Package:get_install_path()`](#packageget_install_path)
     -   [`Package:get_installed_version({callback})`](#packageget_installed_versioncallback)
     -   [`Package:check_new_version({callback})`](#packagecheck_new_versioncallback)
+-   [`InstallContext`](#installcontext)
+    -   [`InstallContext.package`](#installcontextpackage)
+    -   [`InstallContext.handle`](#installcontexthandle)
+    -   [`InstallContext.cwd`](#installcontextcwd)
+    -   [`InstallContext.spawn`](#installcontextspawn)
+    -   [`InstallContext.fs`](#installcontextfs)
+    -   [`InstallContext.requested_version`](#installcontextrequested_version)
+    -   [`InstallContext.stdio_sink`](#installcontextstdio_sink)
 -   [`InstallHandleState`](#installhandlestate)
 -   [`InstallHandle`](#installhandle)
     -   [`InstallHandle.package`](#installhandlepackage)
@@ -58,7 +66,6 @@ something is missing or if something could be improved!
 | languages  | [`PackageLanguage[]`](#package-lang) |
 | install    | `async fun(ctx: InstallContext)`     |
 
-
 ## `Package`
 
 Module: [`"mason-core.package"`](../lua/mason-core/package/init.lua)
@@ -175,6 +182,106 @@ This method will asynchronously check whether there's a newer version of the pac
 Note that this method will result in network calls and will error when there is no internet connection. Also, one should
 call this method with care as to not cause high network traffic as well as respecting user's online privacy.
 
+## `InstallContext`
+
+The `InstallContext` class will be instantiated by Mason every time a package installer is executed. The `install`
+function of a package will receive an instance of `InstallContext` as its first argument.
+
+As the name suggests, this class provides contextual information to be used when installing a package. This includes
+which package is being installed, a `spawn` method that allow you to spawn processes that (i) use the correct working
+directory of the installation, and (ii) automatically registers stdout and stderr with the `InstallHandle`.
+
+### `InstallContext.package`
+
+**Type:** [`Package`](#package)
+
+### `InstallContext.handle`
+
+**Type:** [`InstallHandle`](#installhandle)
+
+### `InstallContext.cwd`
+
+**Type:** [`CwdManager`](#cwdmanager)
+
+### `InstallContext.spawn`
+
+**Type:** [`ContextualSpawn`](#contextualspawn)
+
+### `InstallContext.fs`
+
+**Type:** [`ContextualFs`](#contextualfs)
+
+### `InstallContext.requested_version`
+
+**Type:** `Optional<string>`
+
+### `InstallContext.stdio_sink`
+
+**Type:** `{ stdout: fun(chunk: string), stderr: fun(chunk: string) }`
+
+The `.stdio_sink` property can be used to send stdout or stderr output, to be presented to the user.
+
+Example:
+
+```lua
+Pkg.new {
+    --- ...
+    ---@async
+    ---@param ctx InstallContext
+    install = function (ctx)
+        ctx.stdio_sink.stdout "I am doing stuff\n"
+        ctx.stdio_sink.stderr "Something went wrong!\n"
+    end
+}
+```
+
+## `ContextualFs`
+
+Provides wrapper functions around `mason-core.fs`. These wrapper functions all accept relative paths, which will be
+expanded based on the associated `InstallContext`'s current working directory.
+
+## `ContextualSpawn`
+
+**Type:** `table<string, async fun(opts: SpawnOpts)>`
+
+Provides an asynchronous interface to spawn processes (via libuv). Each spawned process will, by default, be spawned
+with the current working directory of the `InstallContext` it belongs to. stdout & stderr will also automatically be
+registered with the relevant `InstallHandle`.
+
+Example usage:
+
+```lua
+Pkg.new {
+    --- ...
+    ---@async
+    ---@param ctx InstallContext
+    install = function (ctx)
+        ctx.spawn.npm { "install", "some-package" }
+        -- Calls to spawn will raise an error if it exits with a non-OK exit code or signal.
+        pcall(function ()
+            ctx.spawn.commandoesntexist {}
+        end)
+    end
+}
+```
+
+## `CwdManager`
+
+Manages the current working directory of an installation (through `InstallContext`).
+
+### `CwdManager:set({cwd)})`
+
+**Parameters:**
+
+-   `cwd`: `string`
+
+Changes the current working directory to `{cwd}`. `{cwd}` MUST be within the user's configured `install_root_dir`
+setting.
+
+### `CwdManager:get()`
+
+**Returns:** `string`
+
 ## `InstallHandleState`
 
 **Type:** `"IDLE" | "QUEUED" | "ACTIVE" | "CLOSED"`