Release Process

Release Process

Numan's release process is a structured workflow designed to move the Nushell package manager from development to multi-platform distribution. The process involves rigorous CI/CD gates, cross-platform binary builds, and distribution across several package registries including crates.io, Homebrew, and winget.

Continuous Integration and Quality Gates

Before any release can be finalized, the codebase must pass a series of automated quality gates. These gates ensure technical accuracy, performance, and cross-platform compatibility.

CI Requirements

The project enforces the following checks on every Pull Request and before any release build:

• Compilation: Successful cargo build.
• Testing: Execution of the full test suite (376 tests) plus #[ignore] real-Nu acceptance tests.
• Linting: cargo clippy -- -D warnings must pass without issues.
• Formatting: cargo fmt --check ensures adherence to the Rust 2021 edition style.
• Security & Compliance: cargo deny is used to check for security advisories and license compliance.
• MSRV: Verification against the Minimum Supported Rust Version (MSRV) of 1.88.

Release Flow Logic

The following diagram illustrates the transition from code changes to a tagged release.

flowchart TD
    A[Code Changes] --> B[Local Development & Tests]
    B --> C[PR to master]
    C --> D{CI Pass?}
    D -- No --> E[Fix Issues]
    E --> C
    D -- Yes --> F[Squash Merge to master]
    F --> G[Update CHANGELOG.md]
    G --> H[Update Cargo.toml Version]
    H --> I[Push Version Tag]
    I --> J{Tag CI Pass?}
    J -- Yes --> K[Build & Publish]
    J -- No --> L[Rollback/Fix Tag]

Loading

The release process follows a strict "green CI" requirement where tag pushes wait for automated check success before triggers for distribution occur.

Build and Artifact Generation

Numan generates pre-built binaries for Linux, macOS, and Windows. These artifacts are bundled into specific archive formats and include integrity verification files.

Target Platforms and Artifacts

Platform	Architecture	Archive Format	Binary Name
Linux	x86_64	.tar.gz	numan
Windows	x86_64	.zip	numan.exe
macOS	Apple Silicon (aarch64)	.tar.gz	numan
macOS	Intel (x86_64)	.tar.gz	numan

Verification

Each release includes a SHA256SUMS file. This file contains the uppercase hex SHA256 hashes of all installer and binary archives, allowing users and automated packagers to verify the integrity of the downloaded artifacts.

Distribution Channels

The distribution process is multi-faceted, involving direct binary releases and integration into various ecosystem package managers.

1. Crates.io

The project is published as numan-cli. The release involves running cargo package --locked to ensure the environment is reproducible before publishing.

2. Homebrew

A formula is maintained in a dedicated tap (tonythethompson/numan). Updates involve updating the version and SHA256 checksum in the Ruby formula file.

3. Winget (Windows Package Manager)

Release manifests are maintained following the winget-pkgs layout. The tonythethompson.Numan identifier is used.

• Path: manifests/t/tonythethompson/Numan/<version>/
• Schema: Version 1.12.0
• PR Rule: One version per PR to the upstream microsoft/winget-pkgs repository.

4. Official Registry

Starting with v0.1.4, the release process includes cutover to the official production registry.

• Trust Root: official-2026-07-01
• Auto-config: numan init is updated to automatically configure the official registry once the trust root is production-ready.

Release Lifecycle Sequence

The sequence below details the interaction between the developer, GitHub, and the CI environment during a release.

sequenceDiagram
    participant Dev as "Developer"
    participant GH as "GitHub / Git"
    participant CI as "CI (GitHub Actions)"
    participant Reg as "Registries (Crates/Winget/Brew)"

    Dev->>GH: Update version and CHANGELOG
    Dev->>GH: git tag vX.Y.Z
    Dev->>GH: git push --tags
    GH->>CI: Trigger Release Pipeline
    CI->>CI: Run Preflight (Fmt, Clippy, Test)
    activate CI
    Note over CI: Cross-platform builds (Linux/Win/macOS)
    CI->>GH: Create GitHub Release
    CI->>GH: Upload Artifacts & SHA256SUMS
    CI->>Reg: Publish numan-cli to crates.io
    deactivate CI
    Note right of Dev: Update Brew & Winget Manifests

Loading

Conclusion

The release process for Numan emphasizes safety and transparency through the use of immutable artifacts, signed registries, and exhaustive CI verification. By distributing through diverse channels like crates.io, Homebrew, and winget, Numan ensures broad accessibility across all major operating systems while maintaining a consistent and verified installation experience.