diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000000..4c6c97a5d9 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,15 @@ +## Describe your changes + + +## Issue ticket number and link + + +## Checklist before requesting a review + +- [ ] I have successfully tested installation of the package. +- [ ] I have successfully tested the package after installation. + + +## Screenshots + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf70a5157c..07f0eb5006 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,8 +5,9 @@ - [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) > 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 +# 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: + + + +> [!TIP] +> You can emulate different platform ("targets") by providing the `--target=` option to `:MasonInstall`. For example: +> 
:MasonInstall --target=linux_arm64 my-package
+> 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 ``` -
Example: Longer descriptions - -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. -``` - -
+> [!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}}" ``` +
Example: Single, platform independent, release asset @@ -517,6 +558,10 @@ source: ```
+> [!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`. + +--- + +## Open VSX + +[Open VSX](https://open-vsx.org/) is an open-source registry for VS Code extensions. + +Example: + +```yaml +source: + id: pkg:openvsx/vscjava/vscode-java-debug@0.55.0 + download: + file: vscjava.vscode-java-debug-{{version}}.vsix +``` + +
Example: Platform-dependent file + +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/cobol-language-support@2.1.1 + 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 +``` + +