Plugin Backlog & Roadmap
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Plugin Backlog & Roadmap system serves as the strategic planning and execution framework for the numan-plugins repository. Its primary purpose is to manage the intake and promotion of source-only Nushell plugins into signed, hash-pinned binary artifacts suitable for the official numan registry. This system bridges the gap between the approximately 50 most-wanted source-only plugins (e.g., regex, dns, parquet) and the requirements of the registry, which mandates prebuilt release binaries for installation.
Sources: README.md:3-12, manifest.json:208-209
The roadmap outlines a multi-stage lifecycle involving demand-ranked triage, cross-compilation via a CI build-and-sign pipeline, and eventual handoff to the registry. The process is governed by strict trust boundaries, ensuring that while this repository builds and hosts binaries, it never holds signing keys, which remain within the numan-registry environment.
Sources: README.md:14-25, REVIEW.md:20-22
Plugin Promotion Lifecycle
The progression of a plugin from a "demand-ranked" request to an "active" release follows a structured promotion path. This lifecycle ensures that plugins are verified against multiple target operating systems and Nushell versions before being published.
Lifecycle Stages
- Backlog Triage: Source-only plugins are tracked and ranked based on demand within
docs/backlog.json. - Promotion to Active: Entries are moved from the backlog into the
active[]array ofmanifest.jsonin small batches. - CI Validation: The
build-pluginsworkflow verifies tag-to-commit mappings and builds artifacts for the defined target matrix. - Registry Handoff: Generated specifications and release URLs are integrated into the
numan-registryindex.
Sources: README.md:38-42, manifest.json:208-209
The following diagram illustrates the flow of a plugin through the promotion lifecycle:
This diagram shows the end-to-end progression from backlog management to final registry integration.
Sources: README.md:44-55, manifest.json:208-216
Manifest and Build Matrix
The manifest.json file is the central configuration hub for the roadmap, defining which plugins are currently active and their associated metadata.
Data Structure: Active Plugin Entry
Each entry in the active list must contain specific fields to satisfy the build pipeline and registry requirements.
| Field | Description |
|---|---|
repo | The upstream GitHub repository (e.g., owner/repo). |
source_commit | The immutable 40-character hex commit SHA. |
tag | The human-facing version tag used for provenance. |
version | The semantic version of the plugin. |
nu_version | Nushell version compatibility range (e.g., >=0.113.0 <0.114.0). |
exclude_targets | Optional list of Rust triples to skip during the build. |
Sources: manifest.json:7-14, scripts/validate_manifest.py:16-29
Target Matrix
The roadmap supports a wide range of platforms to ensure broad accessibility. The standard build matrix includes:
x86_64-unknown-linux-gnu(Ubuntu latest)aarch64-unknown-linux-gnu(Ubuntu latest cross-compile)x86_64-apple-darwin(macOS 15 Intel)aarch64-apple-darwin(macOS 15)x86_64-pc-windows-msvc(Windows latest)
Sources: manifest.json:210-216, scripts/test_workflow_safety.py:126-140
Release Transaction Architecture
To maintain the roadmap's commitment to immutable release assets, the system employs a "draft-then-finalize" transaction model. This prevents half-published or inconsistent releases from reaching the public.
The sequence diagram details the safety-first release process that ensures asset immutability.
Sources: scripts/release_transaction.py:46-55, REVIEW.md:32-34
Key Safety Invariants
- Immutable Pins: All plugins must pin both a tag and a specific
source_commit. The CI validates that the tag resolves to the commit before building. - Draft Ownership: Releases are created as drafts and are only made public after the complete set of assets (verified by SHA-256) is confirmed.
- Absence Enforcement: The system fails closed if a tag or release already exists, preventing overwriting existing artifacts.
Sources: REVIEW.md:23-30, scripts/ensure_release_absent.py:14-22
Registry Handoff and Integration
The final stage of the roadmap is the handoff to the numan-registry. This is facilitated by the gen_spec.py script, which converts build metadata into a registry-compatible format.
Specification Generation
The generated spec includes:
- Metadata: Name, description, and tags derived from
manifest.json. - Provenance: The
source.revfield preserving the original upstream commit. - Artifacts: A map of targets to their release URLs and internal executable paths.
Sources: scripts/gen_spec.py:122-140, README.md:65-68
This flow shows the transition of data from the build pipeline to the registry's signed index.
Sources: scripts/gen_spec.py:14-25, README.md:49-53
Summary
The Plugin Backlog & Roadmap system provides a robust, cross-platform delivery pipeline for Nushell plugins. By leveraging a strict target matrix, automated manifest validation, and a multi-step release transaction model, the project ensures that high-demand plugins are safely delivered to users as signed binaries. The system's design prioritizes trust and provenance, maintaining a clear separation between binary hosting and the official trust root.
Sources: README.md:14-18, REVIEW.md:20-22