PR Review Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The Pull Request (PR) review process for numan-plugins is designed to maintain the integrity of the binary-delivery pipeline for the Numan registry. Because this repository serves as a feeder for signed, hash-pinned binary artifacts, the review guidelines focus heavily on security, trust boundaries, and build reproducibility.
The scope of reviews covers changes to the build matrix in manifest.json, modifications to packaging scripts, and updates to GitHub Action workflows. The primary goal is to ensure that only immutable, verified upstream source code is cross-compiled and published as release assets without compromising signing keys or registry metadata.
Sources: README.md:1-12, REVIEW.md:1-5
Severity Labels and Triage
Reviewers must categorize findings using specific severity labels to prioritize critical safety and architectural violations.
| Label | Meaning |
|---|---|
| P0 | Signing-key material in repo, mutable/replaced release assets, publish from PR/push, trust-boundary break. |
| P1 | Wrong upstream pin, tag/commit mismatch, incomplete target matrix, broken release transaction, fake readiness. |
| P2 | Spec/manifest doc drift, missing tests for packaging scripts, maintainability issues. |
| P3 | Style, naming, and non-blocking suggestions. |
Sources: REVIEW.md:14-20
Architecture Invariants
Every PR must be audited against these core architectural invariants. Any violation of these principles should be flagged as a P0 or P1 issue.
- Build-Only Scope: This repository is strictly for building and hosting binaries. It must never hold signing keys or Ed25519 trust roots, which remain in
numan-registry. Sources: REVIEW.md:24-27, README.md:20-22 - Immutable Upstream Pins: Entries in
manifest.jsonmust pin a specificsource_commit(40-character SHA) and a human-facingtag. Reviewers must verify that the workflow validates the tag-to-commit mapping. Sources: REVIEW.md:28-29, scripts/validate_manifest.py:102-114 - Asset Immutability: Existing release tags or assets must never be overwritten. Any change to bytes requires a new version or build revision. Sources: REVIEW.md:30-31, README.md:25-27
- Manual Publishing: Releases are only triggered via manual
workflow_dispatchwith a non-emptyonly=package list. Pushes and PRs must only run validation paths. Sources: REVIEW.md:35-36, scripts/test_workflow_safety.py:50-58 - No Registry Mutation: Changes to the registry index or publishing of registry metadata must not occur within this repository. Sources: REVIEW.md:37-38
Build and Release Flow Invariants
The following diagram illustrates the flow that reviewers must protect during PR audits:
The workflow ensures that new releases are assembled as run-owned drafts and verified before being made public.
Sources: README.md:43-54, REVIEW.md:32-33
Review Checklist
Reviewers should use the following checklist for every PR to ensure technical accuracy and safety.
- Trust Boundary: Confirm no private keys, PEM material, or registry secrets are introduced. Sources: REVIEW.md:26-27, 43
- Manifest Integrity: Check that
source_commitis a 40-character hex string andnu_versioncompatibility is defined. Sources: REVIEW.md:44-45, scripts/validate_manifest.py:17, 85-86 - Release Safety: Ensure scripts like
release_transaction.pyandensure_release_absent.pyfail closed if a tag exists or an asset set is incomplete. Sources: REVIEW.md:46-47, scripts/ensure_release_absent.py:23-38 - Cross-Platform Logic: Verify that Windows-specific paths are handled only at Windows boundaries and matrix steps force
bashwhen expanding$MATRIX_*variables. Sources: REVIEW.md:48, scripts/test_workflow_safety.py:100-118
Manifest Validation Logic
The manifest.json file is the source of truth for the build pipeline. PRs modifying this file must adhere to the schema enforced by scripts/validate_manifest.py.
Required Manifest Fields
Each entry in the active[] array must contain:
repo,name,owner,plugin_bintag,source_commit(40-char SHA)version,nu_version,verified_withdescription,tags
Sources: scripts/validate_manifest.py:16-28, 80-87
Target Matrix and Exclusions
Reviewers must ensure that every active plugin specifies which targets it builds for, using the default_targets list as a baseline and exclude_targets for exceptions.
This logic prevents accidental builds of unsupported platforms.
Sources: scripts/validate_manifest.py:44-63, manifest.json:4-10
Release Transaction Security
The project employs a "Draft-then-Finalize" transaction model to prevent "half-published" releases. Reviewers must ensure changes to scripts/release_transaction.py do not break this state machine.
The transaction references the release by a numeric ID (--release-id) to prevent creating duplicate drafts if a tag is temporarily undiscoverable.
Sources: scripts/release_transaction.py:53-100, 163-196, scripts/test_workflow_safety.py:90-98
Summary
PR Review Guidelines for numan-plugins enforce a strict separation between binary production and cryptographic signing. By focusing on immutable upstream pins, deterministic packaging, and manual release triggers, the review process ensures that the Numan registry remains a trusted source for Nushell plugin binaries. Reviewers act as the final gate to prevent trust-boundary breaches or the publication of mutable assets.
Sources: README.md:14-18, REVIEW.md:5-9