Skip to content

docs: clarify registry backend acceptance policy#9543

Merged
jdx merged 5 commits intomainfrom
docs/registry-backend-policy
May 2, 2026
Merged

docs: clarify registry backend acceptance policy#9543
jdx merged 5 commits intomainfrom
docs/registry-backend-policy

Conversation

@jdx
Copy link
Copy Markdown
Owner

@jdx jdx commented May 2, 2026

Summary

The docs gave conflicting signals about which backends are accepted for new registry entries. For example, docs/contributing.md only 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:

  • aqua (preferred) and github are the routinely accepted backends for the registry.
  • 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 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.md and docs/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 (and AGENTS.md via 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

  • Docs build (mise run docs:build) renders without warnings.
  • The asdf warning banners read coherently in the rendered docs.

🤖 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 (aqua preferred, then github/gitlab), Tier 2 (conda with explanation that it doesn’t require conda on PATH), and Tier 3 (npm/pipx/gem/cargo/go/dotnet as rarely accepted due to external runtime/toolchain dependencies).

Updates warnings in asdf-related docs to distinguish registry submissions (use aqua/github) from private/custom plugins (vfox preferred over asdf), and explicitly states new asdf/vfox plugins and ubi are not accepted for new registry entries. Also updates contributing.md/CLAUDE.md to 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.

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-apps
Copy link
Copy Markdown
Contributor

greptile-apps Bot commented May 2, 2026

Greptile Summary

This documentation-only PR aligns registry backend acceptance policy across CLAUDE.md, docs/contributing.md, docs/registry.md, and the asdf backend pages. It introduces a formal three-tier backend hierarchy (Tier 1: aqua/github/gitlab; Tier 2: conda; Tier 3: npm/pipx/gem/cargo/go/dotnet) and explicitly marks new asdf, vfox, and ubi entries as not accepted. The asdf warning banners are refined to distinguish registry submissions from private plugin authoring.

Confidence Score: 5/5

Safe 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

Filename Overview
CLAUDE.md Replaces the one-liner 'New asdf plugins not accepted' with a full four-tier backend policy table, consistently matching docs/contributing.md and docs/registry.md.
docs/contributing.md Expands registry requirements section with the backend tier breakdown and adds guidance to include popularity data in PR descriptions; consistent with all other changed files.
docs/registry.md Reorganises backend listing into tiers, adds conda (Tier 2) and gem (previously absent), and adds explicit 'Not accepted' section for asdf/vfox/ubi.
docs/asdf-legacy-plugins.md Warning banner updated to separate registry submission guidance (aqua/github) from private plugin authoring (vfox preferred over asdf).
docs/dev-tools/backends/asdf.md Same warning banner update as asdf-legacy-plugins.md; correctly distinguishes registry vs. private plugin authoring context.

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
Loading

Reviews (5): Last reviewed commit: "docs: address review feedback — add gitl..." | Re-trigger Greptile

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread CLAUDE.md Outdated
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.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

Suggested change
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.

Comment thread docs/contributing.md Outdated
Comment on lines +627 to +628
- **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
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

Suggested change
- **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

Comment thread docs/contributing.md Outdated
(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.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Consider adding links to the aqua and github backends for consistency with the previous requirement.

Suggested change
Use aqua/github instead.
Use [aqua](/dev-tools/backends/aqua.html) or [github](/dev-tools/backends/github.html) instead.

Comment thread docs/registry.md Outdated
- [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.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Consider adding links to the aqua and github backends for consistency with the list above.

Suggested change
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.

jdx and others added 4 commits May 2, 2026 15:06
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]>
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 2, 2026

Hyperfine Performance

mise x -- echo

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%

@jdx jdx merged commit 9f14454 into main May 2, 2026
37 checks passed
@jdx jdx deleted the docs/registry-backend-policy branch May 2, 2026 17:16
mise-en-dev added a commit that referenced this pull request May 3, 2026
### 🚀 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)
jdx pushed a commit that referenced this pull request May 3, 2026
## 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`
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant