docs: update contributing and add pull request template (mason-org#5038)

.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## Describe your changes
+<!-- Short description of what has been changed and/or added and why -->
+
+## Issue ticket number and link
+<!-- Leave empty if not available -->
+
+## Checklist before requesting a review
+<!-- Refer to the CONTRIBUTING.md for details on testing -->
+- [ ] I have successfully tested installation of the package.
+- [ ] I have successfully tested the package after installation.
+      <!-- For example: successfully starting the LSP server inside Neovim, or successfully integrated linting
+      diagnostics -->
+
+## Screenshots
+<!-- Leave empty if not applicable -->

CONTRIBUTING.md

@@ -5,8 +5,9 @@
 <!--toc:start-->
 - [Contributing guide](#contributing-guide)
   - [Table of Contents](#table-of-contents)
-- [Brief](#brief)
+- [Introduction](#introduction)
 - [Schema](#schema)
+- [Testing](#testing)
 - [The anatomy of a package](#the-anatomy-of-a-package)
 - [Package specification](#package-specification)
   - [`name`](#name)
@@ -22,31 +23,34 @@
 - [Expressions](#expressions)
 - [Examples](#examples)
   - [Common fields](#common-fields)
-  - [cargo](#cargo)
-  - [composer](#composer)
-  - [gem](#gem)
+  - [Cargo](#cargo)
+  - [Composer](#composer)
+  - [Gem](#gem)
   - [GitHub release assets](#github-release-assets)
   - [GitHub build from source](#github-build-from-source)
-  - [golang](#golang)
-  - [luarocks](#luarocks)
+  - [Golang](#golang)
+  - [LuaRocks](#luarocks)
   - [npm](#npm)
-  - [nuget](#nuget)
+  - [Nuget](#nuget)
   - [opam](#opam)
-  - [pypi](#pypi)
+  - [PyPI](#pypi)
+  - [Open VSX](#open-vsx)
 <!--toc:end-->
 
 > 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], and [RFC8174][rfc8174] when, and only when, they appear in all capitals, as shown here.
 
-# Brief
+# Introduction
 
-* Use the YAML language server combined with the [schemastore schema](https://json.schemastore.org/mason-registry.json)
-  to get diagnostics and autocompletion (see [Schema](#schema)).
 * Make sure to follow the [naming guidelines](#name).
 * Refer to the [common fields example](#common-fields) for a good starting point for a new package.
 * Refer to the different [examples](#examples) and/or existing package definitions for further guidance.
-* Testing a package locally is still a bit complicated, open a PR early to make use of the cross-platform CI suite!
+* Testing a package MUST be done locally prior to creating a PR. See [testing](#testing) for more information.
+
+> [!TIP]
+> Use the YAML language server combined with the [schemastore schema](https://json.schemastore.org/mason-registry.json)
+> to get diagnostics and autocompletion (see [Schema](#schema)).
 
 # Schema
 
@@ -61,6 +65,36 @@ Package definitions are validated against a well-defined [JSON schema](./schemas
 
 <img src="https://user-images.githubusercontent.com/6705160/230375252-40dfcd78-dcd3-43c4-8967-c7452384b818.png" height="100" />
 
+# Testing
+
+Testing a package locally can be achieved by configuring the `mason.nvim` client to source package definitions locally
+from your filesystem.
+
+> [!IMPORTANT]
+> In order for `mason.nvim` to be able to parse the YAML files you must have `yq` installed on your system. Tip: install
+> `yq` (`:MasonInstall yq`) from the core registry before testing.
+
+Take note of the path where you have `mason-org/mason-registry` cloned on your file system. To configure `mason.nvim` to
+source packages from there you'll use the `file:` protocol, like so:
+
+```lua
+require("mason").setup {
+  registries = {
+    "file:~/dev/mason-registry"
+  }
+}
+```
+
+Before continuing, make sure Mason has been properly configured to source packages locally by opening the `:Mason`
+window and pressing `g?` to open the help view:
+
+<img src="https://github.com/mason-org/mason-registry/assets/6705160/952e1b0f-6396-492e-9270-e72c26800a98" height="100" />
+
+> [!TIP]
+> You can emulate different platform ("targets") by providing the `--target=` option to `:MasonInstall`. For example:
+> <pre><code>:MasonInstall --target=linux_arm64 my-package</code></pre>  
+> Note that this is only a soft emulation and only impacts how the package definition is parsed.
+
 # The anatomy of a package
 
 Packages are defined following a [well-defined specification](#package-specification). Package definitions are hosted as
@@ -111,6 +145,20 @@ The package name MUST be unique. The name of a package MUST follow the following
 
 Short description of the package. The description SHOULD be sourced from the upstream package directly.
 
+Longer descriptions MUST be split on multiple lines, as to not exceed the max line length (120).
+
+Example:
+
+```yaml
+description: |
+  Lorem ipsum dolor sit amet, officia excepteur ex fugiat reprehenderit enim labore culpa sint ad nisi Lorem pariatur
+  mollit ex esse exercitation amet. Nisi anim cupidatat excepteur officia.
+```
+
+> [!TIP]
+> To automatically format the description across multiple lines, run `:setlocal textwidth=120`, visually select the
+> description and press `gw` (`:help gw`).
+
 ## `homepage`
 
 The homepage of the package. The homepage SHOULD be a public website if available, otherwise it MUST be a URL to the
@@ -203,6 +251,9 @@ share:
     jdtls/plugins/: plugins/
 ```
 
+> [!IMPORTANT]
+> The contents of linked files MUST be compatible with all machines, regardless of hardware architecture.
+
 ## `opt`
 
 The optional, add-on, contents of a package. This is for example useful in situations when a package provides auxiliary
@@ -290,23 +341,12 @@ categories:
   - LSP
 ```
 
-<details><summary>Example: Longer descriptions</summary>
-
-Longer descriptions MUST be split on multiple lines, as to not exceed the max line length.
-
-Example:
-
-```yaml
-description: |
-  Lorem ipsum dolor sit amet, officia excepteur ex fugiat reprehenderit enim labore culpa sint ad nisi Lorem pariatur
-  mollit ex esse exercitation amet. Nisi anim cupidatat excepteur officia.
-```
-
-</details>
+> [!IMPORTANT]
+> The document MUST start with a YAML header notation (`---`).
 
 ---
 
-## cargo
+## Cargo
 
 Example:
 
@@ -364,7 +404,7 @@ source:
 
 ---
 
-## composer
+## Composer
 
 Example:
 
@@ -379,7 +419,7 @@ bin:
 
 ---
 
-## gem
+## Gem
 
 Example:
 
@@ -463,6 +503,7 @@ source:
 bin:
   lua-language-server: "{{source.asset.bin}}"
 ```
+
 </details>
 
 <details><summary>Example: Single, platform independent, release asset</summary>
@@ -517,6 +558,10 @@ source:
 ```
 </details>
 
+> [!IMPORTANT]
+> Linux binaries are commonly compiled for GNU systems. These binaries MUST be associated with a `_gnu` target, e.g.
+> `linux_x64_gnu`.
+
 ---
 
 ## GitHub build from source
@@ -570,7 +615,7 @@ source:
 
 ---
 
-## golang
+## Golang
 
 Example:
 
@@ -596,7 +641,7 @@ source:
 
 ---
 
-## luarocks
+## LuaRocks
 
 Example:
 
@@ -666,7 +711,7 @@ Packages provided in `extra_packages` are passed as-is to npm, so they may requi
 
 ---
 
-## nuget
+## Nuget
 
 Example:
 
@@ -694,7 +739,7 @@ bin:
 
 ---
 
-## pypi
+## PyPI
 
 Example:
 
@@ -734,3 +779,38 @@ source:
 
 Packages provided in `extra_packages` are passed as-is, so they may require version constraints such as `toml==4`.
 </details>
+
+---
+
+## Open VSX
+
+[Open VSX](https://open-vsx.org/) is an open-source registry for VS Code extensions.
+
+Example:
+
+```yaml
+source:
+  id: pkg:openvsx/vscjava/[email protected]
+  download:
+    file: vscjava.vscode-java-debug-{{version}}.vsix
+```
+
+<details><summary>Example: Platform-dependent file</summary>
+
+If the Open VSX package provides platform-dependent files they need to be registered explicitly. In addition to `target`
+and `file`, the `target_platform` field must be defined and correspond to an OpenVSX platform identifier (e.g.
+`linux-x64`).
+
+```yaml
+source:
+  id: pkg:openvsx/BroadcomMFD/[email protected]
+  download:
+    - target: linux_x64
+      file: BroadcomMFD.cobol-language-support-{{ version }}@linux-x64.vsix
+      target_platform: linux-x64
+    - target: darwin_arm64
+      file: BroadcomMFD.cobol-language-support-{{ version }}@darwin-arm64.vsix
+      target_platform: darwin-arm64
+```
+
+</details>