docs: improve plugin documentation with comparisons and template links#7962
Conversation
There was a problem hiding this comment.
Pull request overview
This PR improves the plugin documentation by adding feature comparisons, migration guidance, and template links to help developers choose the right plugin system and get started quickly.
Changes:
- Added feature comparison and hook migration tables to the asdf backend documentation to guide users toward vfox
- Added "Why vfox?" section highlighting cross-platform support, built-in modules, and security features
- Added warning/tip callouts with template repository links across all plugin development guides
- Updated stale
mise-env-samplelinks tomise-env-plugin-templatethroughout the documentation
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| docs/tool-plugin-development.md | Added tip callout linking to the tool plugin template repository |
| docs/plugins.md | Updated environment plugin template link from sample to template |
| docs/environments/index.md | Updated environment plugin template link from sample to template |
| docs/env-plugin-development.md | Added tip callout and updated all sample links to template links |
| docs/dev-tools/backends/vfox.md | Added tip callout and "Why vfox?" section explaining benefits |
| docs/dev-tools/backends/asdf.md | Added warning callout, feature comparison table, and hook migration table |
| docs/dev-tools/backend_architecture.md | Expanded capabilities comparison table with 4 new feature rows |
| docs/backend-plugin-development.md | Added tip callout linking to the backend plugin template repository |
| docs/asdf-legacy-plugins.md | Added warning callout directing users to vfox with comparison links |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Summary of ChangesHello @jdx, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly improves the Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
- Add feature comparison table (asdf vs vfox) and hook migration table to asdf backend docs - Add "Why vfox?" section to vfox backend docs - Add warning callouts to asdf/legacy plugin pages directing users to vfox - Add tip callouts with template links to all 3 plugin development guides - Add 4 new rows to backend capabilities comparison table (built-in modules, security attestations, multi-tool plugins, progress/logging) - Update mise-env-sample links to mise-env-plugin-template Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
jdx
force-pushed
the
docs/plugin-improvements
branch
from
eda32a0 to
bb91989
Compare
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly improves the plugin documentation by adding comparisons between asdf and vfox, migration guides, and steering users towards the modern vfox plugin system. The new tables and warning/tip callouts are very helpful. I've left a few minor suggestions to address some redundant text and to update link texts for consistency where they were missed during the update from mise-env-sample to mise-env-plugin-template. Overall, these are great improvements to the documentation.
| The fastest way to create an environment plugin is to use the [mise-env-plugin-template](https://github.com/jdx/mise-env-plugin-template). | ||
|
|
There was a problem hiding this comment.
This sentence is redundant as the same information is presented in more detail in the tip block that follows. To improve clarity and reduce repetition, I suggest removing this line and the following blank line, letting the tip block introduce the template.
| ## Examples | ||
|
|
||
| - [mise-env-sample](https://github.com/jdx/mise-env-sample) - Simple example showing basic usage | ||
| - [mise-env-sample](https://github.com/jdx/mise-env-plugin-template) - Simple example showing basic usage |
There was a problem hiding this comment.
The link text mise-env-sample is outdated. To maintain consistency with the updated URL, please change the link text to mise-env-plugin-template as well.
| - [mise-env-sample](https://github.com/jdx/mise-env-plugin-template) - Simple example showing basic usage | |
| - [mise-env-plugin-template](https://github.com/jdx/mise-env-plugin-template) - Simple example showing basic usage |
Hyperfine Performance
|
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
mise-2026.2.1 x -- echo |
20.2 ± 0.3 | 19.6 | 21.4 | 1.00 |
mise x -- echo |
20.4 ± 0.5 | 19.7 | 25.1 | 1.01 ± 0.03 |
mise env
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
mise-2026.2.1 env |
19.6 ± 0.5 | 18.9 | 24.6 | 1.00 |
mise env |
19.8 ± 0.4 | 19.0 | 21.3 | 1.01 ± 0.03 |
mise hook-env
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
mise-2026.2.1 hook-env |
20.4 ± 0.3 | 19.7 | 24.0 | 1.00 |
mise hook-env |
20.8 ± 0.5 | 19.9 | 22.6 | 1.02 ± 0.03 |
mise ls
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
mise-2026.2.1 ls |
18.3 ± 0.3 | 17.8 | 19.6 | 1.00 |
mise ls |
18.6 ± 0.5 | 17.9 | 22.5 | 1.02 ± 0.03 |
xtasks/test/perf
| Command | mise-2026.2.1 | mise | Variance |
|---|---|---|---|
| install (cached) | 111ms | 111ms | +0% |
| ls (cached) | 70ms | 70ms | +0% |
| bin-paths (cached) | 73ms | 74ms | -1% |
| task-ls (cached) | 2486ms | ✅ 528ms | +370% |
✅ Performance improvement: task-ls cached is 370%
|
bugbot run |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
### 🚀 Features - **(asset-matcher)** enable `mingw-w64` detection for windows packages by @lchagnoleau in [#7981](#7981) - **(crates/vfox)** add download_path to BackendInstall context by @malept in [#7959](#7959) - **(python)** rework `python.uv_venv_auto` setting by @halms in [#7905](#7905) - add "Did you mean?" suggestions and inactive tool warnings by @jdx in [#7965](#7965) ### 🐛 Bug Fixes - **(hook-env)** skip remote version fetching for uninstalled tools in prefer-offline mode by @jdx in [#7976](#7976) - **(install.sh)** Corret `setup` to `set up` by @gogolok in [#7980](#7980) - retry spawn on ETXTBSY (Text file busy) by @jdx in [#7964](#7964) - improve ToolOptions parsing to support comma separated values by @roele in [#7971](#7971) ### 📚 Documentation - improve plugin documentation with comparisons and template links by @jdx in [#7962](#7962) ### 📦️ Dependency Updates - bump hyper-util, system-configuration, lru, aws-sdk, and others by @jdx in [#7977](#7977) ### Chore - **(vfox)** add LuaCATS type definitions for plugin IDE support by @jdx in [#7961](#7961) - **(vfox)** add `download_path` to `BackendInstallCtx` type defintion by @malept in [#7973](#7973) - add stylua linting for vfox plugin Lua files by @jdx in [#7960](#7960) - use system Rust for PPA builds on Ubuntu 26.04+ by @jdx in [#7956](#7956) ### New Contributors - @gogolok made their first contribution in [#7980](#7980) ## 📦 Aqua Registry Updates #### New Packages (4) - [`autobrr/mkbrr`](https://github.com/autobrr/mkbrr) - [`dodobrands/Peekie`](https://github.com/dodobrands/Peekie) - [`grpc/grpc-java/protoc-gen-grpc-java`](https://github.com/grpc/grpc-java/protoc-gen-grpc-java) - [`str4d/age-plugin-yubikey`](https://github.com/str4d/age-plugin-yubikey) #### Updated Packages (3) - [`biomejs/biome`](https://github.com/biomejs/biome) - [`rust-cross/cargo-zigbuild`](https://github.com/rust-cross/cargo-zigbuild) - [`siderolabs/talos`](https://github.com/siderolabs/talos)
jdx#7962) ## Summary - Add asdf vs vfox feature comparison table and hook migration table to asdf backend docs - Add "Why vfox?" section to vfox backend docs - Add warning callouts on asdf/legacy pages directing users to vfox - Add tip callouts with template links to all 3 plugin development guides (backend, tool, env) - Expand backend capabilities comparison table with 4 new rows (built-in modules, security attestations, multi-tool plugins, progress/logging) - Update stale `mise-env-sample` links to `mise-env-plugin-template` ## Test plan - [ ] `mise run docs` renders correctly - [ ] All links resolve 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Low risk: documentation-only updates (tables, callouts, link/terminology changes) with no runtime behavior impact; main risk is broken links or user confusion from renamed backend references. > > **Overview** > Updates plugin/backend docs to *steer users away from legacy `asdf` plugins* and toward `vfox`, adding prominent warning/tip callouts plus an `asdf` vs `vfox` feature comparison and hook migration table. > > Refreshes backend guidance by expanding the capabilities comparison table, documenting `ubi` as deprecated in favor of `github`, and updating scattered references from `ubi`→`github`. Also adds/updates links to the official backend/tool/env plugin template repositories and replaces stale `mise-env-sample` links with `mise-env-plugin-template`. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 04bbd27. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
### 🚀 Features - **(asset-matcher)** enable `mingw-w64` detection for windows packages by @lchagnoleau in [jdx#7981](jdx#7981) - **(crates/vfox)** add download_path to BackendInstall context by @malept in [jdx#7959](jdx#7959) - **(python)** rework `python.uv_venv_auto` setting by @halms in [jdx#7905](jdx#7905) - add "Did you mean?" suggestions and inactive tool warnings by @jdx in [jdx#7965](jdx#7965) ### 🐛 Bug Fixes - **(hook-env)** skip remote version fetching for uninstalled tools in prefer-offline mode by @jdx in [jdx#7976](jdx#7976) - **(install.sh)** Corret `setup` to `set up` by @gogolok in [jdx#7980](jdx#7980) - retry spawn on ETXTBSY (Text file busy) by @jdx in [jdx#7964](jdx#7964) - improve ToolOptions parsing to support comma separated values by @roele in [jdx#7971](jdx#7971) ### 📚 Documentation - improve plugin documentation with comparisons and template links by @jdx in [jdx#7962](jdx#7962) ### 📦️ Dependency Updates - bump hyper-util, system-configuration, lru, aws-sdk, and others by @jdx in [jdx#7977](jdx#7977) ### Chore - **(vfox)** add LuaCATS type definitions for plugin IDE support by @jdx in [jdx#7961](jdx#7961) - **(vfox)** add `download_path` to `BackendInstallCtx` type defintion by @malept in [jdx#7973](jdx#7973) - add stylua linting for vfox plugin Lua files by @jdx in [jdx#7960](jdx#7960) - use system Rust for PPA builds on Ubuntu 26.04+ by @jdx in [jdx#7956](jdx#7956) ### New Contributors - @gogolok made their first contribution in [jdx#7980](jdx#7980) ## 📦 Aqua Registry Updates #### New Packages (4) - [`autobrr/mkbrr`](https://github.com/autobrr/mkbrr) - [`dodobrands/Peekie`](https://github.com/dodobrands/Peekie) - [`grpc/grpc-java/protoc-gen-grpc-java`](https://github.com/grpc/grpc-java/protoc-gen-grpc-java) - [`str4d/age-plugin-yubikey`](https://github.com/str4d/age-plugin-yubikey) #### Updated Packages (3) - [`biomejs/biome`](https://github.com/biomejs/biome) - [`rust-cross/cargo-zigbuild`](https://github.com/rust-cross/cargo-zigbuild) - [`siderolabs/talos`](https://github.com/siderolabs/talos)
Summary
mise-env-samplelinks tomise-env-plugin-templateTest plan
mise run docsrenders correctly🤖 Generated with Claude Code
Note
Low Risk
Low risk: documentation-only updates (tables, callouts, link/terminology changes) with no runtime behavior impact; main risk is broken links or user confusion from renamed backend references.
Overview
Updates plugin/backend docs to steer users away from legacy
asdfplugins and towardvfox, adding prominent warning/tip callouts plus anasdfvsvfoxfeature comparison and hook migration table.Refreshes backend guidance by expanding the capabilities comparison table, documenting
ubias deprecated in favor ofgithub, and updating scattered references fromubi→github. Also adds/updates links to the official backend/tool/env plugin template repositories and replaces stalemise-env-samplelinks withmise-env-plugin-template.Written by Cursor Bugbot for commit 04bbd27. This will update automatically on new commits. Configure here.