diff --git a/CLAUDE.md b/CLAUDE.md index 79b0f94f57..2c05ac36c9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -38,7 +38,22 @@ Before touching `registry/`, ALWAYS do the following: 5. **If the tool is borderline or numbers are low, warn the user clearly** that the PR is likely to be rejected without reason, and ask if they still want to proceed. Do not soften this — users have repeatedly been surprised when their PR was closed, and the agent should have warned them up front. 6. **Suggest the alternative:** users can install any tool themselves via explicit backend syntax (`mise use aqua:owner/repo`, `mise use github:owner/repo`, `mise use cargo:name`, `mise use npm:name`, etc.) or by writing a [tool plugin](https://mise.en.dev/tool-plugin-development.html). The registry is *only* for shorthand convenience for popular tools — not for enabling installation. -New asdf plugins are also not accepted; use aqua/github backends. +### Backend choice: aqua (preferred) or github + +For registry entries the backend tiers are: + +- **Tier 1 — preferred:** `aqua:`, `github:`, and `gitlab:`. These are the routinely accepted backends. + - **Prefer `aqua:`** when the tool is in the [aqua registry](https://github.com/aquaproj/aqua-registry). Better UX, SLSA verification, and per-version logic. + - **Use `github:`** when the tool isn't in aqua but ships GitHub releases. + - **Use `gitlab:`** for tools released through GitLab. +- **Tier 2 — high bar, but lower than tier 3:** `conda:`. Potentially acceptable when the tool can't be supported via aqua/github. The bar is lower than tier 3 because **the conda backend in mise does not require a separately-installed package manager** — mise downloads and extracts packages directly from anaconda.org via rattler, so users don't need conda/mamba on PATH. Still requires a popular, well-maintained tool. +- **Tier 3 — extremely high bar, almost never accepted:** `npm:`, `pipx:`, `gem:`, `cargo:`, `go:`, `dotnet:`. These all rely on a separately-installed runtime/toolchain being present on PATH (`node`, `python`, `ruby`, `cargo`, `go`, `dotnet`), which is fragile — the wrong version, a missing install, or PATH ordering quirks all break them. `npm:`/`pipx:`/`gem:` are particularly painful because tools installed via them silently bind to whichever `node`/`python`/`ruby` was on PATH at install time. Don't reach for these for a registry PR unless the user has explicitly confirmed @jdx wants it that way for this specific tool. +- **Not accepted at all:** + - **New `asdf:` plugins** — supply-chain security. Use aqua/github instead. + - **New `vfox:` plugins** — same reason. Use aqua/github instead. + - **`ubi:`** is deprecated and will not be accepted under any circumstances. + +Users can still install via any backend themselves with explicit syntax (`mise use vfox:...`, `mise use cargo:...`, etc.) — they just don't get a registry shorthand for it. ## Development Commands diff --git a/docs/asdf-legacy-plugins.md b/docs/asdf-legacy-plugins.md index 1c9376d44d..68b0eb88e0 100644 --- a/docs/asdf-legacy-plugins.md +++ b/docs/asdf-legacy-plugins.md @@ -1,7 +1,9 @@ # asdf (Legacy) Plugins ::: warning -asdf plugins are considered legacy. For new tools, prefer [vfox plugins](/dev-tools/backends/vfox.html) which are written in Lua, work cross-platform (including Windows), and have access to built-in modules. See the [feature comparison](/dev-tools/backends/asdf.html#feature-comparison-asdf-vs-vfox) and [hook migration table](/dev-tools/backends/asdf.html#hook-migration-asdf-to-vfox) for details. +asdf plugins are considered legacy. **New asdf and vfox plugins are not accepted into the [mise registry](https://github.com/jdx/mise/blob/main/registry/) for supply-chain security reasons** — for registry submissions use the [aqua](/dev-tools/backends/aqua.html) (preferred) or [github](/dev-tools/backends/github.html) backend instead. + +If you are writing a private/custom plugin (not for registry submission), prefer [vfox plugins](/dev-tools/backends/vfox.html) over asdf — they're written in Lua, work cross-platform (including Windows), and have access to built-in modules. See the [feature comparison](/dev-tools/backends/asdf.html#feature-comparison-asdf-vs-vfox) and [hook migration table](/dev-tools/backends/asdf.html#hook-migration-asdf-to-vfox) for details. ::: mise maintains compatibility with the asdf plugin ecosystem through its asdf backend. These plugins are considered legacy because they have limitations compared to mise's modern plugin system. diff --git a/docs/contributing.md b/docs/contributing.md index ac3e83dbd6..31c5c4b07e 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -624,13 +624,54 @@ of the full backend specification. When adding a new tool, the following requirements apply (automatically enforced by [GitHub Actions workflow](https://github.com/jdx/mise/blob/main/.github/workflows/registry_comment.yml)): -- **New asdf plugins are not accepted** - Use aqua/github instead - **A test is required in `registry/`** - Must include a `test` field to - verify installation + verify installation. - **Tools may be rejected if they are not notable** - The tool should be reasonably popular and well-maintained. There are no specific guidelines for this and a lot of factors are taken into account. @jdx won't explain why a given tool wasn't - accepted. + accepted. Include a brief popularity summary (stars, downloads, recent release date) in + the PR description so the policy can be applied without re-doing the research. + +#### Backend acceptance tiers + +Which backend you choose for a registry entry matters as much as which tool you +add. Backends fall into the following tiers: + +**Tier 1 — preferred, routinely accepted:** [`aqua`](/dev-tools/backends/aqua.html), +[`github`](/dev-tools/backends/github.html), and [`gitlab`](/dev-tools/backends/gitlab.html). + +- Prefer `aqua` when the tool is in the [aqua registry](https://github.com/aquaproj/aqua-registry) — + it has better UX, SLSA verification, and per-version logic. +- Use `github` when the tool isn't in aqua but ships GitHub releases. +- Use `gitlab` for tools released through GitLab. + +**Tier 2 — high bar, but lower than tier 3:** [`conda`](/dev-tools/backends/conda.html). + +Potentially accepted for tools that can't reasonably be supported via aqua/github. +The bar is lower than tier 3 because **mise's conda backend does not require a +separately-installed package manager** — packages are downloaded and extracted +directly from anaconda.org, with no `conda`/`mamba`/`micromamba` needed on the +user's PATH. The tool still needs to be popular and well-maintained. + +**Tier 3 — very high bar, rarely accepted:** `npm`, `pipx`, `gem`, `cargo`, `go`, +`dotnet`. + +These all depend on a separately-installed runtime or toolchain being present on +the user's PATH (`node`, `python`, `ruby`, `cargo`, `go`, `dotnet`), which is +fragile — `npm`/`pipx`/`gem` in particular silently bind tools to whichever +`node`/`python`/`ruby` happened to be on PATH at install time, which breaks when +versions change or the runtime isn't installed. Accepted only when no aqua/github +option exists and the tool is widely used. Discuss with @jdx before submitting. + +**Not accepted:** `asdf`, `vfox`, `ubi`. + +- **New `asdf` plugins** — supply-chain security. Use [aqua](/dev-tools/backends/aqua.html) or [github](/dev-tools/backends/github.html) instead. +- **New `vfox` plugins** — same reason. Use aqua/github instead. +- **`ubi`** is deprecated and is not accepted for new registry entries. + +Users can still install via any backend themselves with explicit syntax +(`mise use vfox:owner/repo`, `mise use cargo:name`, etc.) — they just don't get +a registry shorthand for it. ### Registry Format diff --git a/docs/dev-tools/backends/asdf.md b/docs/dev-tools/backends/asdf.md index 746f5e76a4..c94ea39201 100644 --- a/docs/dev-tools/backends/asdf.md +++ b/docs/dev-tools/backends/asdf.md @@ -1,7 +1,9 @@ # asdf Backend ::: warning -asdf plugins are considered legacy. For new tools, prefer [vfox plugins](/dev-tools/backends/vfox.html) which are written in Lua, work cross-platform (including Windows), and have access to built-in modules for HTTP, JSON, HTML parsing, and more. +asdf plugins are considered legacy. **New asdf and vfox plugins are not accepted into the [mise registry](https://github.com/jdx/mise/blob/main/registry/) for supply-chain security reasons** — for registry submissions use the [aqua](/dev-tools/backends/aqua.html) (preferred) or [github](/dev-tools/backends/github.html) backend instead. + +If you are writing a private/custom plugin (not for registry submission), prefer [vfox plugins](/dev-tools/backends/vfox.html) over asdf — they're written in Lua, work cross-platform (including Windows), and have access to built-in modules for HTTP, JSON, HTML parsing, and more. ::: `asdf` is the original backend for mise. diff --git a/docs/registry.md b/docs/registry.md index fa1015912d..7e40c55285 100644 --- a/docs/registry.md +++ b/docs/registry.md @@ -28,18 +28,35 @@ If a tool is not available in the registry, you can install it by its full name. In addition to built-in [core tools](/core-tools.html), `mise` supports a variety of [backends](/dev-tools/backends/) to install tools. -In general, the preferred [backend](/dev-tools/backends/) to use for new tools is the following: +Backends fall into the following acceptance tiers for new registry entries: + +**Tier 1 — preferred, routinely accepted:** - [aqua](./dev-tools/backends/aqua.html) - offers the most features and security while not requiring plugins - [github](./dev-tools/backends/github.html) - for tools that are not available in the aqua registry, but are available on GitHub - [gitlab](./dev-tools/backends/gitlab.html) - for tools that are not available in the aqua registry, but are available on GitLab -- [pipx](./dev-tools/backends/pipx.html) - only for python tools, requires python to be installed but this generally would always be the case for python tools -- [npm](./dev-tools/backends/npm.html) - only for node tools, requires node to be installed but this generally would always be the case for node tools -- [go](./dev-tools/backends/go.html) - only for go tools, requires go to be installed to compile. Because go tools can be distributed as a single binary, aqua/github are definitely preferred. -- [cargo](./dev-tools/backends/cargo.html) - only for rust tools, requires rust to be installed to compile. Because rust tools can be distributed as a single binary, aqua/github are definitely preferred. -- [dotnet](./dev-tools/backends/dotnet.html) - only for dotnet tools, requires dotnet to be installed to compile. Because dotnet tools can be distributed as a single binary, aqua/github are definitely preferred. -New vfox and asdf tools are almost never accepted for supply-chain security reasons. +**Tier 2 — high bar, but lower than tier 3:** + +- [conda](./dev-tools/backends/conda.html) - potentially accepted for tools that can't reasonably be supported via aqua/github. The bar is lower than tier 3 because mise's conda backend does not require a separately-installed package manager — packages are fetched and extracted directly from anaconda.org with no `conda`/`mamba`/`micromamba` needed on PATH. + +**Tier 3 — very high bar, rarely accepted:** + +- [pipx](./dev-tools/backends/pipx.html) - only for python tools, requires `python` on PATH +- [npm](./dev-tools/backends/npm.html) - only for node tools, requires `node` on PATH +- [gem](./dev-tools/backends/gem.html) - only for ruby tools, requires `ruby` on PATH +- [go](./dev-tools/backends/go.html) - only for go tools, requires `go` to be installed to compile. Because go tools can be distributed as a single binary, aqua/github are definitely preferred. +- [cargo](./dev-tools/backends/cargo.html) - only for rust tools, requires `cargo` to be installed to compile. Because rust tools can be distributed as a single binary, aqua/github are definitely preferred. +- [dotnet](./dev-tools/backends/dotnet.html) - only for dotnet tools, requires `dotnet` to be installed to compile. Because dotnet tools can be distributed as a single binary, aqua/github are definitely preferred. + +These all depend on a separately-installed runtime/toolchain on PATH, which is fragile — `npm`/`pipx`/`gem` in particular silently bind tools to whichever `node`/`python`/`ruby` happened to be on PATH at install time. + +**Not accepted:** + +- New `vfox` and `asdf` tools are not accepted for supply-chain security reasons — use [`aqua`](./dev-tools/backends/aqua.html) (preferred) or [`github`](./dev-tools/backends/github.html) instead. +- The `ubi` backend is deprecated and is not accepted for new registry entries. + +Users can still install via any backend themselves with explicit syntax (`mise use vfox:owner/repo`, `mise use cargo:name`, etc.) — they just don't get a registry shorthand for it. ### Backends Priority