docs: clarify registry backend acceptance policy#9543
Conversation
Multiple docs gave conflicting signals about which backends are accepted for new registry entries. Align them on a single policy: - aqua (preferred) and github are the routinely accepted backends. - New asdf and vfox plugins are not accepted (supply-chain security). - ubi is deprecated and is not accepted for new registry entries. - Other backends (npm, pipx, cargo, gem, go, dotnet, etc.) have a very high bar and require prior agreement. Updates docs/contributing.md (the requirements list now mentions vfox and ubi, not just asdf), docs/registry.md, and the warning banners in docs/asdf-legacy-plugins.md and docs/dev-tools/backends/asdf.md (which previously steered users toward vfox for new tools, contradicting the registry policy). Also extends CLAUDE.md / AGENTS.md so AI agents apply the same rules. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Greptile SummaryThis documentation-only PR aligns registry backend acceptance policy across Confidence Score: 5/5Safe to merge — documentation-only changes with no runtime or build logic modifications. All changes are documentation. Policy is stated consistently across every file touched. No code, tests, or build configuration is affected. No files require special attention. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[New registry entry?] --> B{Is tool in aqua registry?}
B -- Yes --> C[Use aqua: Tier 1]
B -- No --> D{Ships GitHub/GitLab releases?}
D -- GitHub --> E[Use github: Tier 1]
D -- GitLab --> F[Use gitlab: Tier 1]
D -- No --> G{Python/Node/Ruby/Go/Rust/dotnet tool?}
G -- conda available --> H[Use conda: Tier 2 — high bar]
G -- runtime-dependent --> I[npm/pipx/gem/cargo/go/dotnet Tier 3 — very high bar]
G -- asdf or vfox plugin --> J[Not accepted — supply-chain security]
G -- ubi --> K[Not accepted — deprecated]
I --> L{Discuss with @jdx first}
H --> L
L -- Approved --> M[Submit PR with popularity data]
L -- Not approved --> N[Use explicit backend syntax instead]
J --> N
K --> N
Reviews (5): Last reviewed commit: "docs: address review feedback — add gitl..." | Re-trigger Greptile |
There was a problem hiding this comment.
Code Review
This pull request updates documentation across several files to clarify the policy for tool registry submissions, explicitly stating that only aqua and github backends are routinely accepted while asdf, vfox, and ubi are restricted or deprecated for security reasons. The review feedback identifies a contradiction in CLAUDE.md regarding the ubi backend's status and points out inconsistent link formatting in the contributing guide. Additionally, suggestions were provided to include cross-links to the preferred backends for better documentation navigation.
| New asdf plugins are also not accepted; use aqua/github backends. | ||
| ### Backend choice: aqua (preferred) or github | ||
|
|
||
| For registry entries, **only `aqua:` and `github:` are routinely accepted.** Every other backend (`vfox:`, `asdf:`, `npm:`, `pipx:`, `cargo:`, `gem:`, `go:`, `ubi:`, etc.) has an **extremely high** bar — these are rarely accepted into the registry and submitting one without prior agreement from @jdx is almost certain to be rejected. |
There was a problem hiding this comment.
The inclusion of ubi: in this list of backends with a 'high bar' contradicts line 49, which states it will not be accepted under any circumstances. It should be removed from this list for clarity.
| For registry entries, **only `aqua:` and `github:` are routinely accepted.** Every other backend (`vfox:`, `asdf:`, `npm:`, `pipx:`, `cargo:`, `gem:`, `go:`, `ubi:`, etc.) has an **extremely high** bar — these are rarely accepted into the registry and submitting one without prior agreement from @jdx is almost certain to be rejected. | |
| For registry entries, **only `aqua:` and `github:` are routinely accepted.** Every other backend (`vfox:`, `asdf:`, `npm:`, `pipx:`, `cargo:`, `gem:`, `go:`, etc.) has an **extremely high** bar — these are rarely accepted into the registry and submitting one without prior agreement from @jdx is almost certain to be rejected. |
| - **New asdf and vfox plugins are not accepted** - Use [aqua](dev-tools/backends/aqua.md) | ||
| (preferred) or [github](dev-tools/backends/github.md) instead. This is a supply-chain |
There was a problem hiding this comment.
The links use the .md extension and lack a leading slash, which is inconsistent with other documentation files (e.g., docs/asdf-legacy-plugins.md) that use root-relative paths with the .html extension. This might cause broken links in the rendered documentation.
| - **New asdf and vfox plugins are not accepted** - Use [aqua](dev-tools/backends/aqua.md) | |
| (preferred) or [github](dev-tools/backends/github.md) instead. This is a supply-chain | |
| - **New asdf and vfox plugins are not accepted** - Use [aqua](/dev-tools/backends/aqua.html) | |
| (preferred) or [github](/dev-tools/backends/github.html) instead. This is a supply-chain |
| (preferred) or [github](dev-tools/backends/github.md) instead. This is a supply-chain | ||
| security policy. | ||
| - **The `ubi` backend is deprecated and will not be accepted** for new registry entries. | ||
| Use aqua/github instead. |
| - [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. | ||
| New `vfox` and `asdf` tools are not accepted for supply-chain security reasons — use `aqua` (preferred) or `github` instead. The `ubi` backend is deprecated and is not accepted for new registry entries. |
There was a problem hiding this comment.
Consider adding links to the aqua and github backends for consistency with the list above.
| New `vfox` and `asdf` tools are not accepted for supply-chain security reasons — use `aqua` (preferred) or `github` instead. The `ubi` backend is deprecated and is not accepted for new registry entries. | |
| 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. |
The previous docs lumped conda in with npm/cargo/etc. as "almost never accepted." That's too strict — for tools that genuinely can't be supported via aqua/github (e.g. conda-native scientific packages only distributed through conda-forge), conda is the legitimate distribution channel. The bar is still high, but lower than the language-specific backends. Updates docs/contributing.md, docs/registry.md, and CLAUDE.md so the registry policy describes three tiers: aqua/github (preferred), conda (high bar, but lower), language-specific backends (extremely high bar). Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
The previous wording leaned on "conda is the legitimate distribution channel for some ecosystems," but the load-bearing reason is simpler: mise's conda backend downloads and extracts packages directly from anaconda.org via rattler — it does not require conda/mamba/micromamba on PATH. By contrast, npm/pipx/gem/cargo/go/dotnet all depend on a separately- installed runtime or toolchain being present on the user's PATH, which is fragile. npm/pipx/gem in particular silently bind tools to whichever node/python/ruby was on PATH at install time, which breaks when versions change or the runtime isn't installed at all. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Promote the tier framing from CLAUDE.md into the user-facing docs: - Tier 1 (preferred, routinely accepted): aqua, github, gitlab - Tier 2 (high bar, but lower than tier 3): conda — does not require a separately-installed package manager - Tier 3 (very high bar, rarely accepted): pipx, npm, gem, go, cargo, dotnet — all depend on a runtime/toolchain on PATH - Not accepted: new asdf/vfox plugins, deprecated ubi Updates docs/contributing.md and docs/registry.md so contributors see the same structure the AGENTS.md guidance uses. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
- Add gitlab to Tier 1 in docs/contributing.md and CLAUDE.md so it matches docs/registry.md (Greptile finding). - Convert docs/contributing.md backend links from `dev-tools/backends/X.md` to root-relative `/dev-tools/backends/X.html` so they render correctly, matching the convention used elsewhere in docs/ (gemini-code-assist finding). - Add aqua/github links in the "Not accepted" section of docs/registry.md for parity with the rest of the page. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Hyperfine Performance
|
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
mise-2026.4.28 x -- echo |
23.5 ± 0.2 | 22.9 | 24.6 | 1.00 |
mise x -- echo |
24.1 ± 0.2 | 23.5 | 25.0 | 1.03 ± 0.01 |
mise env
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
mise-2026.4.28 env |
23.1 ± 0.6 | 22.3 | 29.9 | 1.00 |
mise env |
23.4 ± 0.3 | 22.8 | 25.2 | 1.01 ± 0.03 |
mise hook-env
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
mise-2026.4.28 hook-env |
23.8 ± 0.3 | 23.0 | 27.0 | 1.00 |
mise hook-env |
24.2 ± 0.3 | 23.5 | 25.8 | 1.02 ± 0.02 |
mise ls
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
mise-2026.4.28 ls |
20.8 ± 0.3 | 20.3 | 21.6 | 1.00 |
mise ls |
21.3 ± 0.3 | 20.7 | 22.3 | 1.02 ± 0.02 |
xtasks/test/perf
| Command | mise-2026.4.28 | mise | Variance |
|---|---|---|---|
| install (cached) | 156ms | 162ms | -3% |
| ls (cached) | 78ms | 81ms | -3% |
| bin-paths (cached) | 83ms | 85ms | -2% |
| task-ls (cached) | 792ms | 789ms | +0% |
### 🚀 Features - **(conda)** graduate conda backend out of experimental by @jdx in [#9544](#9544) - **(deps)** Add dart and flutter providers by @tjarvstrand in [#9505](#9505) - **(registry)** add neo4j by @mnm364 in [#9525](#9525) - **(registry)** add rustfs by @mnm364 in [#9530](#9530) - **(task)** support exclusion patterns in task sources by @jlarmstrongiv in [#9496](#9496) - **(vfox)** add stat function to lua file module by @esteve in [#9497](#9497) ### 🐛 Bug Fixes - **(backend)** flag regex prerelease versions by @jdx in [#9500](#9500) - **(backend)** mark -nightly/-canary/-experimental as prereleases by @jdx in [#9523](#9523) - **(backend)** suppress no-versions warning for unresolved-latest backends by @jdx in [#9548](#9548) - **(backend)** include dotnet prereleases from package flags by @jdx in [#9551](#9551) - **(backend)** scope PEP 440 prerelease detection to Python backends by @jdx in [#9558](#9558) - **(cargo)** Apply install_env during cargo install by @c22 in [#9502](#9502) - **(copr)** drop epel-9 chroots since rust >= 1.91 is unavailable by @jdx in [#9484](#9484) - **(github)** skip attestations on non-default api_url by @jdx in [#9486](#9486) - **(github)** retry ip allow list errors without auth by @risu729 in [#9506](#9506) - **(http)** update versions host tracking endpoint by @jdx in [#9527](#9527) - **(install)** don't warn for configured tools when version is passed via CLI by @jdx in [#9522](#9522) - **(install)** refresh latest before installing missing tools by @jdx in [#9545](#9545) - **(install)** don't cache nonexistent install paths by @jdx in [#9553](#9553) - **(lockfile)** don't propagate ad-hoc CLI overrides into the project lockfile by @jdx in [#9562](#9562) - **(plugin)** detect plugin types after cloning by @risu729 in [#9540](#9540) - **(release)** pass --no-git-checks to aube publish by @jdx in [#9483](#9483) - **(task)** convert PATH to MSYS Unix form when spawning POSIX shells on Windows by @JamBalaya56562 in [#9547](#9547) ### 📚 Documentation - **(contributing)** require popularity check for registry PRs by @jdx in [7bbeebe](7bbeebe) - **(watch)** update pitchfork domain to en.dev by @risu729 in [#9536](#9536) - document ghtkn GitHub token setup by @jdx in [#9546](#9546) - clarify registry backend acceptance policy by @jdx in [#9543](#9543) - Change exec command to use bash for variable echo by @kuboon in [#9567](#9567) ### 🧪 Testing - **(e2e)** run test-tool targets in parallel by @jdx in [#9564](#9564) - **(e2e)** run tests in parallel by @jdx in [#9563](#9563) - **(e2e)** bind-mount /tmp on disk and surface failed tests in CI summary by @jdx in [#9570](#9570) - **(tasks)** migrate test_task_help atask to usage field by @jdx in [#9549](#9549) ### 📦️ Dependency Updates - update fedora:45 docker digest to 8b838b3 by @renovate[bot] in [#9507](#9507) - update ghcr.io/jdx/mise:deb docker digest to f02194c by @renovate[bot] in [#9509](#9509) - update taiki-e/install-action digest to 7769b73 by @renovate[bot] in [#9512](#9512) - update ghcr.io/jdx/mise:alpine docker digest to 581f8a8 by @renovate[bot] in [#9508](#9508) - update rust crate ctor to v0.10.1 by @renovate[bot] in [#9515](#9515) - update ghcr.io/jdx/mise:rpm docker digest to a5c9655 by @renovate[bot] in [#9510](#9510) - update rust docker digest to a9cfb75 by @renovate[bot] in [#9511](#9511) - update rust crate age to v0.11.3 by @renovate[bot] in [#9514](#9514) - update rust crate jiff to v0.2.24 by @renovate[bot] in [#9516](#9516) - update dependency vitepress-plugin-tabs to ^0.9.0 by @renovate[bot] in [#9518](#9518) - update autofix-ci/action action to v1.3.4 by @renovate[bot] in [#9513](#9513) - update rust crate usage-lib to v3.2.1 by @renovate[bot] in [#9517](#9517) - update apple-actions/import-codesign-certs action to v7 by @renovate[bot] in [#9519](#9519) - update taiki-e/install-action digest to 51cd0b8 by @renovate[bot] in [#9531](#9531) - exclude taiki-e/install-action from renovate by @jdx in [#9532](#9532) - update rust crate blake3 to v1.8.5 by @renovate[bot] in [#9533](#9533) ### 📦 Registry - enable shellcheck on windows by @zeitlinger in [#9487](#9487) - add google-java-format by @zeitlinger in [#9488](#9488) - add expert ([aqua:expert-lsp/expert](https://github.com/expert-lsp/expert)) by @AlternateRT in [#9498](#9498) - update entry for checkmake by @eread in [#9504](#9504) - add systemctl-tui ([aqua:rgwood/systemctl-tui](https://github.com/rgwood/systemctl-tui)) by @2xdevv in [#9521](#9521) - add codon by @3w36zj6 in [#9538](#9538) - add tool yr (backend:github:VirusTotal/yara-x) by @adam-moss in [#9542](#9542) - add tool betterleaks (backend:aqua/betterleaks/betterleaks) by @adam-moss in [#9541](#9541) - add `git-filter-repo` by @garysassano in [#9550](#9550) - add umoci ([aqua:opencontainers/umoci](https://github.com/opencontainers/umoci)) by @2xdevv in [#9555](#9555) - add aqua backend for elixir-ls by @AlternateRT in [#9557](#9557) - deny inline backend options by @risu729 in [#9565](#9565) ### Chore - **(ci)** fail registry tests without summary by @jdx in [#9559](#9559) - **(ci)** use !cancelled() instead of always() for test-ci aggregator by @jdx in [#9569](#9569) - **(ci)** use namespace runners for ci jobs by @jdx in [#9561](#9561) - **(config)** deprecate shorthands_file setting by @risu729 in [#9534](#9534) - **(docs)** remove shrill.en.dev analytics script by @jdx in [#9539](#9539) - **(release)** replace bc with awk in release-plz star formatting by @jdx in [d7f177f](d7f177f) - bump hk to 1.44.3 by @jdx in [#9493](#9493) - invert CLAUDE.md/AGENTS.md so AGENTS.md is canonical by @jdx in [#9560](#9560) - set dev profile debug to 1 by @jdx in [#9572](#9572) ### New Contributors - @kuboon made their first contribution in [#9567](#9567) - @AlternateRT made their first contribution in [#9557](#9557) - @2xdevv made their first contribution in [#9555](#9555) - @adam-moss made their first contribution in [#9541](#9541) - @jlarmstrongiv made their first contribution in [#9496](#9496) - @tjarvstrand made their first contribution in [#9505](#9505)
## Summary - Remove stale plugin docs wording that tells users to add tools to the mise registry after choosing aqua/github. - Keep registry acceptance policy centralized in the registry/contributing docs. ## Context This follows the recently merged registry policy clarification in mise PR #9543, which documents backend acceptance tiers and the high bar for new registry entries. ## Verification - `git diff --check`
Summary
The docs gave conflicting signals about which backends are accepted for new registry entries. For example,
docs/contributing.mdonly said "new asdf plugins are not accepted" (no mention of vfox), while the asdf backend warning banners actively pointed users at vfox for "new tools" — contradicting the registry policy that new vfox plugins are also rejected.This PR aligns everything on a single policy:
ubiis deprecated and is not accepted for new registry entries.npm,pipx,cargo,gem,go,dotnet, etc.) have a very high bar and need prior agreement.Files updated:
docs/contributing.md— requirements list now mentions vfox/ubi, and asks contributors to include popularity data in the PR description.docs/registry.md— tightened the existing "new vfox/asdf almost never accepted" line and added the ubi deprecation.docs/asdf-legacy-plugins.mdanddocs/dev-tools/backends/asdf.md— warning banners now explicitly distinguish "registry submissions → aqua/github" from "private/custom plugin authoring → vfox preferred over asdf", instead of unconditionally steering people at vfox.CLAUDE.md(andAGENTS.mdvia symlink) — adds a "Registry Submissions: READ THIS FIRST" section so AI agents apply the same rules: check popularity numbers, include them in the PR body, default to aqua/github, warn the user when the bar isn't met.Test plan
mise run docs:build) renders without warnings.🤖 Generated with Claude Code
Note
Low Risk
Low risk: documentation-only changes that clarify (and slightly tighten) the policy for which backends are acceptable for new
registry/entries, with no runtime or registry data changes.Overview
Clarifies and standardizes the registry backend acceptance policy across docs and the agent guide: Tier 1 (
aquapreferred, thengithub/gitlab), Tier 2 (condawith explanation that it doesn’t require conda on PATH), and Tier 3 (npm/pipx/gem/cargo/go/dotnetas rarely accepted due to external runtime/toolchain dependencies).Updates warnings in
asdf-related docs to distinguish registry submissions (useaqua/github) from private/custom plugins (vfox preferred over asdf), and explicitly states newasdf/vfoxplugins andubiare not accepted for new registry entries. Also updatescontributing.md/CLAUDE.mdto require including tool popularity metrics in registry PR descriptions and to warn users when a submission is likely to be rejected.Reviewed by Cursor Bugbot for commit 80ad13c. Bugbot is set up for automated code reviews on this repo. Configure here.