nushell-plugins/guides/COMPLETE_VERSION_UPDATE_GUIDE.md

Complete Nushell Version Update Guide

Version: 1.0 Last Updated: 2025-10-18 Applies To: All future Nushell version updates

---

📋 Table of Contents

1. Overview
2. Quick Start
3. Complete Update Workflow
4. Plugin Updates
5. Distribution Creation
6. Troubleshooting
7. Reference

---

Overview

This guide documents the complete workflow for updating the nushell-plugins repository to a new Nushell version, including:

• ✅ Downloading and building new Nushell version
• ✅ Updating all plugin dependencies
• ✅ Creating distribution packages
• ✅ Creating bin archives
• ✅ Validating syntax and compatibility
• ✅ Generating documentation

What's Automated

The update system provides semi-automated workflows with strategic manual checkpoints:

• Fully Automated: Download, build, dependency updates, packaging
• Manual Checkpoints: Breaking changes review, build verification, final approval

Directory Structure

nushell-plugins/
├── updates/           # Version-specific documentation
│   ├── 107/          # Nushell 0.107.x updates
│   ├── 108/          # Nushell 0.108.x updates
│   └── 109/          # Future versions...
├── guides/           # General guides (this file)
├── scripts/          # Automation scripts
│   ├── complete_update.nu              # 🆕 ALL-IN-ONE script
│   ├── update_nushell_version.nu       # Main orchestrator
│   ├── update_all_plugins.nu           # 🆕 Update all plugins
│   ├── create_full_distribution.nu     # 🆕 Complete packaging
│   └── lib/common_lib.nu               # Shared utilities
├── nushell/          # Nushell source (submodule or downloaded)
├── nu_plugin_*/      # Custom plugins
├── distribution/     # Full distribution packages
└── bin_archives/     # Plugin-only archives

---

Quick Start

Option 1: Complete Update (Recommended)

Single command to update everything:

# Update to specific version (all-in-one)
./scripts/complete_update.nu 0.108.0

# Update to latest release
./scripts/complete_update.nu --latest

# What it does:
# 1. Downloads Nushell 0.108.0
# 2. Builds with MCP + all features
# 3. Updates ALL plugin dependencies
# 4. Creates full distribution packages
# 5. Creates bin archives
# 6. Generates documentation
# 7. Validates everything

Time: ~20-30 minutes (mostly build time)

Option 2: Step-by-Step Update

For more control, use individual scripts:

# Step 1: Update Nushell core
./scripts/update_nushell_version.nu 0.108.0

# Step 2: Update all plugins
./scripts/update_all_plugins.nu 0.108.0

# Step 3: Create distributions
./scripts/create_full_distribution.nu

Time: ~25-35 minutes (with review time)

Option 3: Manual Update

For maximum control, follow the detailed workflow below.

---

Complete Update Workflow

Phase 1: Preparation (5 minutes)

1.1 Check Current State

# Check current nushell version
nu --version

# Check git status
git status

# Check for uncommitted changes
git diff --stat

1.2 Create Backup

# Stash any local changes
git stash save "backup before nushell update"

# Create backup branch (optional)
git branch backup-before-0.108.0

1.3 Review Release Notes

# Download release notes
curl -sL https://api.github.com/repos/nushell/nushell/releases/tags/0.108.0 | jq .body

# Or visit GitHub
open https://github.com/nushell/nushell/releases/tag/0.108.0

What to look for:

• Breaking changes
• Deprecated commands
• New features
• Migration guides

---

Phase 2: Nushell Core Update (15-20 minutes)

2.1 Download Nushell Source

# Download specific version
./scripts/download_nushell.nu 0.108.0 --clean

# Or download latest
./scripts/download_nushell.nu --latest

Output:

[INFO] Downloading Nushell 0.108.0 from GitHub...
[SUCCESS] Downloaded: 15.2 MB
[SUCCESS] Extracted 43 crates
[SUCCESS] Nushell 0.108.0 ready at: ./nushell/

2.2 Analyze Features

# Check available features
./scripts/analyze_nushell_features.nu --validate

# Show all features
./scripts/analyze_nushell_features.nu --show-all

# Show dependency tree for specific feature
./scripts/analyze_nushell_features.nu tree mcp

Desired features (configurable in script):

• mcp - Model Context Protocol
• plugin - Plugin system
• sqlite - SQLite support
• trash-support - Trash bin
• system-clipboard - Clipboard integration

2.3 Build Nushell

# Build with all features
./scripts/build_nushell.nu

# Or manually
cd nushell
cargo build --release --workspace \
  --features "mcp,plugin,sqlite,trash-support,system-clipboard,rustls-tls"
cd ..

Build time: ~10-15 minutes Output: nushell/target/release/nu (42+ MB)

2.4 Verify Build

# Check version
./nushell/target/release/nu -c "version"

# Verify features
./nushell/target/release/nu -c "version | get features"

# Test basic commands
./nushell/target/release/nu -c "1 + 1"
./nushell/target/release/nu -c "ls | length"

---

Phase 3: Plugin Updates (10 minutes)

3.1 Audit Current Plugins

# Check all plugin dependencies
./scripts/audit_crate_dependencies.nu --export

# Check specific plugin
./scripts/audit_crate_dependencies.nu --plugin nu_plugin_image

# Show dependency matrix
./scripts/audit_crate_dependencies.nu matrix

Output:

Total plugins: 11
Clean: 8
With issues: 3

Plugins with Version Issues:
[ERROR] nu_plugin_image
  • nu-plugin: found 0.107.1, expected 0.108.0
  • nu-protocol: found 0.107.1, expected 0.108.0

3.2 Detect Breaking Changes

# Scan for breaking changes
./scripts/detect_breaking_changes.nu --scan-plugins --export

Output:

Breaking Change #1: Command Rename
  Old: into value
  New: detect type

  Affected Plugins:
    • nu_plugin_image: 2 occurrences
    • nu_plugin_hashes: 1 occurrence

3.3 Update Plugin Versions

# Update all plugins automatically
./scripts/update_all_plugins.nu 0.108.0

# Or use existing script with confirmation
./scripts/update_nu_versions.nu update

What it does:

• Updates nu-plugin dependency to 0.108.0
• Updates nu-protocol dependency to 0.108.0
• Updates all other nu-* dependencies
• Preserves path dependencies
• Creates backup of Cargo.toml files

3.4 Build All Plugins

# Build all plugins
just build

# Or manually
for plugin in nu_plugin_*; do
    echo "Building $plugin..."
    cd $plugin && cargo build --release && cd ..
done

3.5 Test Plugin Compatibility

# Test all plugins
./scripts/test_plugin_compatibility.nu

# Register plugins with new nushell
./scripts/register_plugins.nu

---

Phase 4: Distribution Creation (5 minutes)

4.1 Collect Binaries

# Collect all binaries for distribution
./scripts/collect_full_binaries.nu

# Or use justfile
just collect-full

What it collects:

• nushell/target/release/nu → distribution/darwin-arm64/nu
• nushell/target/release/nu_plugin_* → distribution/darwin-arm64/
• Custom nu_plugin_*/target/release/nu_plugin_* → distribution/darwin-arm64/

4.2 Create Distribution Packages

# Create packages for all platforms
./scripts/create_distribution_packages.nu --all-platforms

# Or for current platform only
./scripts/create_distribution_packages.nu

# Or use justfile
just pack-full          # Current platform
just pack-full-all      # All platforms

Generates:

distribution/
├── darwin-arm64/
│   ├── nu
│   ├── nu_plugin_*
│   ├── install.nu
│   ├── manifest.json
│   └── README.md
├── linux-x86_64/
│   └── ...
└── packages/
    ├── nushell-full-darwin-arm64-0.108.0.tar.gz
    ├── nushell-full-linux-x86_64-0.108.0.tar.gz
    └── checksums.txt

4.3 Create Bin Archives

# Create plugin-only archives
just pack

# Or manually
./scripts/create_bin_archives.nu

Generates:

bin_archives/
├── nu_plugin_clipboard-0.108.0-darwin-arm64.tar.gz
├── nu_plugin_image-0.108.0-darwin-arm64.tar.gz
├── nu_plugin_hashes-0.108.0-darwin-arm64.tar.gz
└── ...

---

Phase 5: Validation & Documentation (5 minutes)

5.1 Validate Syntax

# Test critical syntax patterns
./scripts/validate_code_rules.nu

# Manual tests
./nushell/target/release/nu -c 'def test [x: string]: nothing -> string { $x }; test "hello"'
./nushell/target/release/nu -c 'let name = "Alice"; print $"Hello ($name)"'

5.2 Run Quality Checks

# Full quality workflow
just quality-flow

# Individual checks
just check    # cargo check
just lint     # clippy
just fmt      # format
just test     # tests

5.3 Generate Documentation

# Generate update summary
./scripts/generate_update_docs.nu 0.108.0

Creates in updates/108/:

• NUSHELL_0.108_UPDATE_SUMMARY.md - Complete summary
• MIGRATION_0.108.0.md - Migration guide
• VALIDATION_REPORT.md - Test results
• CHANGES.md - Breaking changes

5.4 Verify Installation

# Test installation from distribution
cd distribution/darwin-arm64
./install.nu --verify
cd ../..

# Verify plugins registered
./nushell/target/release/nu -c "plugin list"

---

Phase 6: Finalization (5 minutes)

6.1 Review Changes

# Check git status
git status

# Review diffs
git diff

# Check modified files
git diff --name-only

6.2 Create Commit

# Add all changes
git add -A

# Create descriptive commit
git commit -m "chore: update to Nushell 0.108.0

- Updated nushell core to 0.108.0 with MCP support
- Updated all plugin dependencies to 0.108.0
- Fixed critical syntax bugs in best_nushell_code.md
- Created full distribution packages
- Generated comprehensive documentation
- All tests passing

Breaking changes:
- into value → detect type (deprecated, still works)
- Stream error handling now raises errors

Features added:
- MCP (Model Context Protocol) support
- SQLite integration
- System clipboard access
- Trash support

Files modified:
- nushell/ (updated to 0.108.0)
- nu_plugin_*/Cargo.toml (dependency updates)
- best_nushell_code.md (syntax corrections)
- scripts/ (8 new automation scripts)
- updates/108/ (comprehensive documentation)
"

6.3 Push Changes

# Push to remote
git push origin main

# Or create a PR
git checkout -b update/nushell-0.108.0
git push origin update/nushell-0.108.0
gh pr create --title "Update to Nushell 0.108.0" --body "See commit message for details"

---

Plugin Updates

Individual Plugin Update

To update a single plugin:

# Update specific plugin
cd nu_plugin_image
cargo update
cargo build --release

# Test
../nushell/target/release/nu
> plugin add target/release/nu_plugin_image
> plugin list
> # Test plugin commands

Bulk Plugin Update

To update all plugins:

# Use the all-in-one script
./scripts/update_all_plugins.nu 0.108.0

# Or manually
for plugin in nu_plugin_*; do
    echo "Updating $plugin..."
    cd $plugin

    # Update Cargo.toml
    sed -i '' 's/nu-plugin = { version = "0.107.1"/nu-plugin = { version = "0.108.0"/' Cargo.toml
    sed -i '' 's/nu-protocol = { version = "0.107.1"/nu-protocol = { version = "0.108.0"/' Cargo.toml

    # Build
    cargo build --release

    cd ..
done

Plugin Testing Checklist

• Plugin builds without errors
• Plugin registers with new nushell
• Plugin commands execute correctly
• Plugin output format is correct
• No deprecation warnings
• Tests pass
• Clippy is happy

---

Distribution Creation

Full Distribution (Nushell + All Plugins)

What it includes:

• Nushell binary (nu)
• All system plugins (8 plugins)
• All custom plugins (your plugins)
• Installation script
• Documentation
• Manifest with versions

Creation:

# Complete workflow
./scripts/create_full_distribution.nu --all-platforms --checksums

# What it does:
# 1. Collects nu binary from nushell/target/release/
# 2. Collects system plugins from nushell/target/release/
# 3. Collects custom plugins from nu_plugin_*/target/release/
# 4. Creates directory structure
# 5. Copies installation scripts
# 6. Generates manifest.json
# 7. Creates README.md
# 8. Packages as .tar.gz
# 9. Generates SHA256 checksums

Output:

distribution/packages/
├── nushell-full-darwin-arm64-0.108.0.tar.gz (120 MB)
├── nushell-full-linux-x86_64-0.108.0.tar.gz (110 MB)
├── nushell-full-windows-x86_64-0.108.0.zip (115 MB)
└── checksums.txt

Plugin-Only Distribution

What it includes:

• Only custom plugins (nu_plugin_*)
• Individual plugin archives
• Lightweight packages

Creation:

# Create plugin archives
just pack

# Manual creation
./scripts/create_bin_archives.nu

Output:

bin_archives/
├── nu_plugin_clipboard-0.108.0-darwin-arm64.tar.gz (2 MB)
├── nu_plugin_image-0.108.0-darwin-arm64.tar.gz (8 MB)
├── nu_plugin_hashes-0.108.0-darwin-arm64.tar.gz (3 MB)
└── ...

Cross-Platform Builds

For cross-platform distributions:

# Install cross-compilation tools
rustup target add x86_64-unknown-linux-gnu
rustup target add x86_64-pc-windows-gnu
rustup target add aarch64-unknown-linux-gnu

# Build for all platforms
just build-full-cross

# Create distributions for all
just pack-full-all

---

Troubleshooting

Common Issues

Build Failures

Symptom: Cargo build fails with dependency errors

# Solution: Clean and rebuild
cargo clean
cargo build --release

Symptom: Missing system dependencies

# macOS
brew install openssl pkg-config

# Ubuntu/Debian
sudo apt install libssl-dev pkg-config build-essential

# Fedora
sudo dnf install openssl-devel pkgconf gcc

Plugin Registration Fails

Symptom: Plugins don't register

# Check plugin path
ls -la target/release/nu_plugin_*

# Register manually
nu -c "plugin add target/release/nu_plugin_NAME"

# Verify
nu -c "plugin list"

Version Mismatches

Symptom: "version mismatch" errors

# Check versions
./scripts/audit_crate_dependencies.nu

# Fix automatically
./scripts/update_nu_versions.nu update

# Verify
./scripts/audit_crate_dependencies.nu

Distribution Package Issues

Symptom: Missing files in distribution

# Verify collection
ls distribution/darwin-arm64/

# Recollect binaries
./scripts/collect_full_binaries.nu --force

# Rebuild package
./scripts/create_distribution_packages.nu

Debug Mode

Enable debug logging for more information:

# Set log level
export LOG_LEVEL=DEBUG

# Run with debug
./scripts/complete_update.nu 0.108.0

# Save complete log
./scripts/complete_update.nu 0.108.0 2>&1 | tee update.log

Rollback Procedure

If something goes wrong:

# Option 1: Restore from stash
git stash pop

# Option 2: Reset to backup branch
git reset --hard backup-before-0.108.0

# Option 3: Restore submodule
cd nushell
git checkout 0.107.1
cd ..

# Rebuild old version
cargo clean
cargo build --release

---

Reference

Quick Command Reference

# Update everything
./scripts/complete_update.nu 0.108.0

# Update nushell only
./scripts/update_nushell_version.nu 0.108.0

# Update plugins only
./scripts/update_all_plugins.nu 0.108.0

# Create distributions
./scripts/create_full_distribution.nu

# Validate
./scripts/validate_code_rules.nu

# Check status
./scripts/update_nushell_version.nu status

# Clean up
./scripts/update_nushell_version.nu clean

Justfile Commands

# Build
just build                 # All plugins
just build-nushell         # Nushell core
just build-full            # Everything

# Test
just test                  # All tests
just quality-flow          # Complete quality checks

# Distribution
just collect-full          # Collect binaries
just pack-full             # Create packages
just pack-full-all         # All platforms

# Version management
just validate-nushell      # Check version consistency
just fix-nushell          # Fix version mismatches

Environment Variables

# Override defaults
export NUSHELL_SOURCE_DIR="/custom/path"
export UPDATE_TMP_DIR="/tmp/nu-update"
export LOG_LEVEL="DEBUG"
export UPDATE_AUTO_APPROVE="false"

File Locations

Key Files:
- scripts/complete_update.nu          # All-in-one update script
- scripts/update_nushell_version.nu   # Nushell update orchestrator
- scripts/update_all_plugins.nu       # Plugin updater
- scripts/create_full_distribution.nu # Distribution packager
- updates/108/                        # Version-specific docs
- guides/                             # This guide

Generated Files:
- updates/108/NUSHELL_0.108_UPDATE_SUMMARY.md
- updates/108/MIGRATION_0.108.0.md
- updates/108/VALIDATION_REPORT.md
- distribution/packages/*.tar.gz
- bin_archives/*.tar.gz

Support

Documentation:

• This guide: guides/COMPLETE_VERSION_UPDATE_GUIDE.md
• Version docs: updates/108/
• Automation: updates/108/NUSHELL_UPDATE_AUTOMATION.md
• Migration: updates/108/MIGRATION_0.108.0.md

Scripts:

• scripts/ - All automation scripts
• justfile - Quick commands
• etc/plugin_registry.toml - Plugin configuration

Online Resources:

• Nushell Book
• Plugin Guide
• GitHub Releases

---

Guide Version: 1.0 Last Updated: 2025-10-18 Next Review: With Nushell 0.109.0 release