nushell-plugins/guides/complete-version-update-guide.md

# Complete Nushell Version Update Guide\n\n**Version**: 2.0\n**Last Updated**: 2025-11-30\n**Current Nushell Version**: 0.109.0\n**Applies To**: All future Nushell version updates\n\n---\n\n## 📋 Table of Contents\n\n1. [Overview](#overview)\n2. [Quick Start](#quick-start)\n3. [Complete Update Workflow](#complete-update-workflow)\n4. [Plugin Updates](#plugin-updates)\n5. [Distribution Creation](#distribution-creation)\n6. [Troubleshooting](#troubleshooting)\n7. [Reference](#reference)\n\n---\n\n## Overview\n\nThis guide documents the **complete workflow** for updating the nushell-plugins repository to a new Nushell version, including:\n\n- ✅ Downloading and building new Nushell version\n- ✅ Updating all plugin dependencies\n- ✅ Creating distribution packages\n- ✅ Creating bin archives\n- ✅ Validating syntax and compatibility\n- ✅ Generating documentation\n\n### What's Automated\n\nThe update system provides **semi-automated workflows** with strategic manual checkpoints:\n\n- **Fully Automated**: Download, build, dependency updates, packaging\n- **Manual Checkpoints**: Breaking changes review, build verification, final approval\n\n### Directory Structure\n\n```plaintext\nnushell-plugins/\n├── updates/           # Version-specific documentation\n│   ├── 107/          # Nushell 0.107.x updates\n│   ├── 108/          # Nushell 0.108.x updates\n│   └── 109/          # Future versions...\n├── guides/           # General guides (this file)\n├── scripts/          # Automation scripts\n│   ├── complete_update.nu              # 🆕 ALL-IN-ONE script\n│   ├── update_nushell_version.nu       # Main orchestrator\n│   ├── update_all_plugins.nu           # 🆕 Update all plugins\n│   ├── create_full_distribution.nu     # 🆕 Complete packaging\n│   └── lib/common_lib.nu               # Shared utilities\n├── nushell/          # Nushell source (submodule or downloaded)\n├── nu_plugin_*/      # Custom plugins\n├── distribution/     # Full distribution packages\n└── bin_archives/     # Plugin-only archives\n```\n\n---\n\n## What's New in Version 2.0 (Nushell 0.109.0 Update)\n\n### Smart Version Management\n\n**Problem Solved**: Plugin package versions were being confused with Nushell versions.\n\n**Solution**: Intelligent version detection in `update_all_plugins.nu`:\n\n- **Always updates**: `nu-plugin` dependency (all plugins → 0.109.0)\n- **Selectively updates**: Package version only if it matches previous Nushell version (0.108.0)\n- **Preserves**: All plugin-specific versions (0.1.0, 1.1.0, 1.2.12, etc.)\n\n**Example**:\n\n```plaintext\nBefore:  nu_plugin_clipboard package version = 0.108.0\nAfter:   nu_plugin_clipboard package version = 0.109.0  ✅ Updated\n\nBefore:  nu_plugin_auth package version = 0.1.0\nAfter:   nu_plugin_auth package version = 0.1.0         ✅ Preserved\n```\n\n### Script Improvements\n\n1. **String Interpolation Fix** (Rule 18 Compliance)\n   - Escaped literal parentheses: `\(DRY RUN\)` instead of `(DRY RUN)`\n\n2. **Template Generation Fix**\n   - Now correctly generates `register-plugins.nu` (registers plugins)\n   - Previously incorrectly named `install.nu` (should only install binaries)\n\n3. **Bootstrap Auto-Detection**\n   - `install.sh` automatically detects local binaries\n   - No need to manually specify `--source-path`\n\n### Documentation\n\n- Added `updates/109/UPDATE_SUMMARY.md` - Complete 0.109.0 changes\n- Added `updates/109/MIGRATION_0.109.0.md` - Migration guide\n- Updated `guides/COMPLETE_VERSION_UPDATE_GUIDE.md` - This guide\n\n---\n\n## Quick Start\n\n### Option 1: Complete Update (Recommended)\n\n**Single command to update everything:**\n\n```bash\n# Update to specific version (all-in-one)\n./scripts/complete_update.nu 0.109.0\n\n# Update to latest release\n./scripts/complete_update.nu --latest\n\n# What it does:\n# 1. Downloads Nushell 0.109.0\n# 2. Builds with MCP + all features\n# 3. Updates ALL plugin dependencies (0.109.0)\n# 4. Selectively updates plugin package versions (only if 0.108.0)\n# 5. Creates full distribution packages\n# 6. Creates bin archives\n# 7. Generates documentation\n# 8. Validates everything\n```\n\n**Time**: ~20-30 minutes (mostly build time)\n\n### Option 2: Step-by-Step Update\n\n**For more control, use individual scripts:**\n\n```bash\n# Step 1: Update Nushell core\n./scripts/update_nushell_version.nu 0.108.0\n\n# Step 2: Update all plugins\n./scripts/update_all_plugins.nu 0.108.0\n\n# Step 3: Create distributions\n./scripts/create_full_distribution.nu\n```\n\n**Time**: ~25-35 minutes (with review time)\n\n### Option 3: Manual Update\n\n**For maximum control, follow the detailed workflow below.**\n\n---\n\n## Complete Update Workflow\n\n### Phase 1: Preparation (5 minutes)\n\n#### 1.1 Check Current State\n\n```bash\n# Check current nushell version\nnu --version\n\n# Check git status\ngit status\n\n# Check for uncommitted changes\ngit diff --stat\n```\n\n#### 1.2 Create Backup\n\n```bash\n# Stash any local changes\ngit stash save "backup before nushell update"\n\n# Create backup branch (optional)\ngit branch backup-before-0.108.0\n```\n\n#### 1.3 Review Release Notes\n\n```bash\n# Download release notes\ncurl -sL https://api.github.com/repos/nushell/nushell/releases/tags/0.108.0 | jq .body\n\n# Or visit GitHub\nopen https://github.com/nushell/nushell/releases/tag/0.108.0\n```\n\n**What to look for:**\n\n- Breaking changes\n- Deprecated commands\n- New features\n- Migration guides\n\n---\n\n### Phase 2: Nushell Core Update (15-20 minutes)\n\n#### 2.1 Download Nushell Source\n\n```bash\n# Download specific version\n./scripts/download_nushell.nu 0.108.0 --clean\n\n# Or download latest\n./scripts/download_nushell.nu --latest\n```\n\n**Output:**\n\n```plaintext\n[INFO] Downloading Nushell 0.108.0 from GitHub...\n[SUCCESS] Downloaded: 15.2 MB\n[SUCCESS] Extracted 43 crates\n[SUCCESS] Nushell 0.108.0 ready at: ./nushell/\n```\n\n#### 2.2 Analyze Features\n\n```bash\n# Check available features\n./scripts/analyze_nushell_features.nu --validate\n\n# Show all features\n./scripts/analyze_nushell_features.nu --show-all\n\n# Show dependency tree for specific feature\n./scripts/analyze_nushell_features.nu tree mcp\n```\n\n**Desired features** (configurable in script):\n\n- `mcp` - Model Context Protocol\n- `plugin` - Plugin system\n- `sqlite` - SQLite support\n- `trash-support` - Trash bin\n- `system-clipboard` - Clipboard integration\n\n#### 2.3 Build Nushell\n\n```bash\n# Build with all features\n./scripts/build_nushell.nu\n\n# Or manually\ncd nushell\ncargo build --release --workspace \n  --features "mcp,plugin,sqlite,trash-support,system-clipboard,rustls-tls"\ncd ..\n```\n\n**Build time**: ~10-15 minutes\n**Output**: `nushell/target/release/nu` (42+ MB)\n\n#### 2.4 Verify Build\n\n```bash\n# Check version\n./nushell/target/release/nu -c "version"\n\n# Verify features\n./nushell/target/release/nu -c "version | get features"\n\n# Test basic commands\n./nushell/target/release/nu -c "1 + 1"\n./nushell/target/release/nu -c "ls | length"\n```\n\n---\n\n### Phase 3: Plugin Updates (10 minutes)\n\n#### 3.1 Audit Current Plugins\n\n```bash\n# Check all plugin dependencies\n./scripts/audit_crate_dependencies.nu --export\n\n# Check specific plugin\n./scripts/audit_crate_dependencies.nu --plugin nu_plugin_image\n\n# Show dependency matrix\n./scripts/audit_crate_dependencies.nu matrix\n```\n\n**Output:**\n\n```plaintext\nTotal plugins: 11\nClean: 8\nWith issues: 3\n\nPlugins with Version Issues:\n[ERROR] nu_plugin_image\n  • nu-plugin: found 0.107.1, expected 0.108.0\n  • nu-protocol: found 0.107.1, expected 0.108.0\n```\n\n#### 3.2 Detect Breaking Changes\n\n```bash\n# Scan for breaking changes\n./scripts/detect_breaking_changes.nu --scan-plugins --export\n```\n\n**Output:**\n\n```plaintext\nBreaking Change #1: Command Rename\n  Old: into value\n  New: detect type\n\n  Affected Plugins:\n    • nu_plugin_image: 2 occurrences\n    • nu_plugin_hashes: 1 occurrence\n```\n\n#### 3.3 Update Plugin Versions\n\n```bash\n# Update all plugins automatically\n./scripts/update_all_plugins.nu 0.108.0\n\n# Or use existing script with confirmation\n./scripts/update_nu_versions.nu update\n```\n\n**What it does:**\n\n- Updates `nu-plugin` dependency to 0.108.0\n- Updates `nu-protocol` dependency to 0.108.0\n- Updates all other `nu-*` dependencies\n- Preserves path dependencies\n- Creates backup of Cargo.toml files\n\n#### 3.4 Build All Plugins\n\n```bash\n# Build all plugins\njust build\n\n# Or manually\nfor plugin in nu_plugin_*; do\n    echo "Building $plugin..."\n    cd $plugin && cargo build --release && cd ..\ndone\n```\n\n#### 3.5 Test Plugin Compatibility\n\n```bash\n# Test all plugins\n./scripts/test_plugin_compatibility.nu\n\n# Register plugins with new nushell\n./scripts/register_plugins.nu\n```\n\n---\n\n### Phase 4: Distribution Creation (5 minutes)\n\n#### 4.1 Collect Binaries\n\n```bash\n# Collect all binaries for distribution\n./scripts/collect_full_binaries.nu\n\n# Or use justfile\njust collect-full\n```\n\n**What it collects:**\n\n- `nushell/target/release/nu` → `distribution/darwin-arm64/nu`\n- `nushell/target/release/nu_plugin_*` → `distribution/darwin-arm64/`\n- Custom `nu_plugin_*/target/release/nu_plugin_*` → `distribution/darwin-arm64/`\n\n#### 4.2 Create Distribution Packages\n\n```bash\n# Create packages for all platforms\n./scripts/create_distribution_packages.nu --all-platforms\n\n# Or for current platform only\n./scripts/create_distribution_packages.nu\n\n# Or use justfile\njust pack-full          # Current platform\njust pack-full-all      # All platforms\n```\n\n**Generates:**\n\n```plaintext\ndistribution/\n├── darwin-arm64/\n│   ├── nu\n│   ├── nu_plugin_*\n│   ├── install.nu\n│   ├── manifest.json\n│   └── README.md\n├── linux-x86_64/\n│   └── ...\n└── packages/\n    ├── nushell-full-darwin-arm64-0.108.0.tar.gz\n    ├── nushell-full-linux-x86_64-0.108.0.tar.gz\n    └── checksums.txt\n```\n\n#### 4.3 Create Bin Archives\n\n```bash\n# Create plugin-only archives\njust pack\n\n# Or manually\n./scripts/create_bin_archives.nu\n```\n\n**Generates:**\n\n```plaintext\nbin_archives/\n├── nu_plugin_clipboard-0.108.0-darwin-arm64.tar.gz\n├── nu_plugin_image-0.108.0-darwin-arm64.tar.gz\n├── nu_plugin_hashes-0.108.0-darwin-arm64.tar.gz\n└── ...\n```\n\n---\n\n### Phase 5: Validation & Documentation (5 minutes)\n\n#### 5.1 Validate Syntax\n\n```bash\n# Test critical syntax patterns\n./scripts/validate_code_rules.nu\n\n# Manual tests\n./nushell/target/release/nu -c 'def test [x: string]: nothing -> string { $x }; test "hello"'\n./nushell/target/release/nu -c 'let name = "Alice"; print $"Hello ($name)"'\n```\n\n#### 5.2 Run Quality Checks\n\n```bash\n# Full quality workflow\njust quality-flow\n\n# Individual checks\njust check    # cargo check\njust lint     # clippy\njust fmt      # format\njust test     # tests\n```\n\n#### 5.3 Generate Documentation\n\n```bash\n# Generate update summary\n./scripts/generate_update_docs.nu 0.108.0\n```\n\n**Creates in `updates/108/`:**\n\n- `NUSHELL_0.108_UPDATE_SUMMARY.md` - Complete summary\n- `MIGRATION_0.108.0.md` - Migration guide\n- `VALIDATION_REPORT.md` - Test results\n- `CHANGES.md` - Breaking changes\n\n#### 5.4 Verify Installation\n\n```bash\n# Test installation from distribution\ncd distribution/darwin-arm64\n./install.nu --verify\ncd ../..\n\n# Verify plugins registered\n./nushell/target/release/nu -c "plugin list"\n```\n\n---\n\n### Phase 6: Finalization (5 minutes)\n\n#### 6.1 Review Changes\n\n```bash\n# Check git status\ngit status\n\n# Review diffs\ngit diff\n\n# Check modified files\ngit diff --name-only\n```\n\n#### 6.2 Create Commit\n\n```bash\n# Add all changes\ngit add -A\n\n# Create descriptive commit\ngit commit -m "chore: update to Nushell 0.108.0\n\n- Updated nushell core to 0.108.0 with MCP support\n- Updated all plugin dependencies to 0.108.0\n- Fixed critical syntax bugs in best_nushell_code.md\n- Created full distribution packages\n- Generated comprehensive documentation\n- All tests passing\n\nBreaking changes:\n- into value → detect type (deprecated, still works)\n- Stream error handling now raises errors\n\nFeatures added:\n- MCP (Model Context Protocol) support\n- SQLite integration\n- System clipboard access\n- Trash support\n\nFiles modified:\n- nushell/ (updated to 0.108.0)\n- nu_plugin_*/Cargo.toml (dependency updates)\n- best_nushell_code.md (syntax corrections)\n- scripts/ (8 new automation scripts)\n- updates/108/ (comprehensive documentation)\n"\n```\n\n#### 6.3 Push Changes\n\n```bash\n# Push to remote\ngit push origin main\n\n# Or create a PR\ngit checkout -b update/nushell-0.108.0\ngit push origin update/nushell-0.108.0\ngh pr create --title "Update to Nushell 0.108.0" --body "See commit message for details"\n```\n\n---\n\n## Plugin Updates\n\n### Individual Plugin Update\n\nTo update a single plugin:\n\n```bash\n# Update specific plugin\ncd nu_plugin_image\ncargo update\ncargo build --release\n\n# Test\n../nushell/target/release/nu\n> plugin add target/release/nu_plugin_image\n> plugin list\n> # Test plugin commands\n```\n\n### Bulk Plugin Update\n\nTo update all plugins:\n\n```bash\n# Use the all-in-one script\n./scripts/update_all_plugins.nu 0.108.0\n\n# Or manually\nfor plugin in nu_plugin_*; do\n    echo "Updating $plugin..."\n    cd $plugin\n\n    # Update Cargo.toml\n    sed -i '' 's/nu-plugin = { version = "0.107.1"/nu-plugin = { version = "0.108.0"/' Cargo.toml\n    sed -i '' 's/nu-protocol = { version = "0.107.1"/nu-protocol = { version = "0.108.0"/' Cargo.toml\n\n    # Build\n    cargo build --release\n\n    cd ..\ndone\n```\n\n### Plugin Testing Checklist\n\n- [ ] Plugin builds without errors\n- [ ] Plugin registers with new nushell\n- [ ] Plugin commands execute correctly\n- [ ] Plugin output format is correct\n- [ ] No deprecation warnings\n- [ ] Tests pass\n- [ ] Clippy is happy\n\n---\n\n## Distribution Creation\n\n### Full Distribution (Nushell + All Plugins)\n\n**What it includes:**\n\n- Nushell binary (`nu`)\n- All system plugins (8 plugins)\n- All custom plugins (your plugins)\n- Installation script\n- Documentation\n- Manifest with versions\n\n**Creation:**\n\n```bash\n# Complete workflow\n./scripts/create_full_distribution.nu --all-platforms --checksums\n\n# What it does:\n# 1. Collects nu binary from nushell/target/release/\n# 2. Collects system plugins from nushell/target/release/\n# 3. Collects custom plugins from nu_plugin_*/target/release/\n# 4. Creates directory structure\n# 5. Copies installation scripts\n# 6. Generates manifest.json\n# 7. Creates README.md\n# 8. Packages as .tar.gz\n# 9. Generates SHA256 checksums\n```\n\n**Output:**\n\n```plaintext\ndistribution/packages/\n├── nushell-full-darwin-arm64-0.108.0.tar.gz (120 MB)\n├── nushell-full-linux-x86_64-0.108.0.tar.gz (110 MB)\n├── nushell-full-windows-x86_64-0.108.0.zip (115 MB)\n└── checksums.txt\n```\n\n### Plugin-Only Distribution\n\n**What it includes:**\n\n- Only custom plugins (nu_plugin_*)\n- Individual plugin archives\n- Lightweight packages\n\n**Creation:**\n\n```bash\n# Create plugin archives\njust pack\n\n# Manual creation\n./scripts/create_bin_archives.nu\n```\n\n**Output:**\n\n```plaintext\nbin_archives/\n├── nu_plugin_clipboard-0.108.0-darwin-arm64.tar.gz (2 MB)\n├── nu_plugin_image-0.108.0-darwin-arm64.tar.gz (8 MB)\n├── nu_plugin_hashes-0.108.0-darwin-arm64.tar.gz (3 MB)\n└── ...\n```\n\n### Cross-Platform Builds\n\nFor cross-platform distributions:\n\n```bash\n# Install cross-compilation tools\nrustup target add x86_64-unknown-linux-gnu\nrustup target add x86_64-pc-windows-gnu\nrustup target add aarch64-unknown-linux-gnu\n\n# Build for all platforms\njust build-full-cross\n\n# Create distributions for all\njust pack-full-all\n```\n\n---\n\n## Troubleshooting\n\n### Common Issues\n\n#### Build Failures\n\n**Symptom**: Cargo build fails with dependency errors\n\n```bash\n# Solution: Clean and rebuild\ncargo clean\ncargo build --release\n```\n\n**Symptom**: Missing system dependencies\n\n```bash\n# macOS\nbrew install openssl pkg-config\n\n# Ubuntu/Debian\nsudo apt install libssl-dev pkg-config build-essential\n\n# Fedora\nsudo dnf install openssl-devel pkgconf gcc\n```\n\n#### Plugin Registration Fails\n\n**Symptom**: Plugins don't register\n\n```bash\n# Check plugin path\nls -la target/release/nu_plugin_*\n\n# Register manually\nnu -c "plugin add target/release/nu_plugin_NAME"\n\n# Verify\nnu -c "plugin list"\n```\n\n#### Version Mismatches\n\n**Symptom**: "version mismatch" errors\n\n```bash\n# Check versions\n./scripts/audit_crate_dependencies.nu\n\n# Fix automatically\n./scripts/update_nu_versions.nu update\n\n# Verify\n./scripts/audit_crate_dependencies.nu\n```\n\n#### Distribution Package Issues\n\n**Symptom**: Missing files in distribution\n\n```bash\n# Verify collection\nls distribution/darwin-arm64/\n\n# Recollect binaries\n./scripts/collect_full_binaries.nu --force\n\n# Rebuild package\n./scripts/create_distribution_packages.nu\n```\n\n### Debug Mode\n\nEnable debug logging for more information:\n\n```bash\n# Set log level\nexport LOG_LEVEL=DEBUG\n\n# Run with debug\n./scripts/complete_update.nu 0.108.0\n\n# Save complete log\n./scripts/complete_update.nu 0.108.0 2>&1 | tee update.log\n```\n\n### Rollback Procedure\n\nIf something goes wrong:\n\n```bash\n# Option 1: Restore from stash\ngit stash pop\n\n# Option 2: Reset to backup branch\ngit reset --hard backup-before-0.108.0\n\n# Option 3: Restore submodule\ncd nushell\ngit checkout 0.107.1\ncd ..\n\n# Rebuild old version\ncargo clean\ncargo build --release\n```\n\n---\n\n## Reference\n\n### Quick Command Reference\n\n```bash\n# Update everything\n./scripts/complete_update.nu 0.108.0\n\n# Update nushell only\n./scripts/update_nushell_version.nu 0.108.0\n\n# Update plugins only\n./scripts/update_all_plugins.nu 0.108.0\n\n# Create distributions\n./scripts/create_full_distribution.nu\n\n# Validate\n./scripts/validate_code_rules.nu\n\n# Check status\n./scripts/update_nushell_version.nu status\n\n# Clean up\n./scripts/update_nushell_version.nu clean\n```\n\n### Justfile Commands\n\n```bash\n# Build\njust build                 # All plugins\njust build-nushell         # Nushell core\njust build-full            # Everything\n\n# Test\njust test                  # All tests\njust quality-flow          # Complete quality checks\n\n# Distribution\njust collect-full          # Collect binaries\njust pack-full             # Create packages\njust pack-full-all         # All platforms\n\n# Version management\njust validate-nushell      # Check version consistency\njust fix-nushell          # Fix version mismatches\n```\n\n### Environment Variables\n\n```bash\n# Override defaults\nexport NUSHELL_SOURCE_DIR="/custom/path"\nexport UPDATE_TMP_DIR="/tmp/nu-update"\nexport LOG_LEVEL="DEBUG"\nexport UPDATE_AUTO_APPROVE="false"\n```\n\n### File Locations\n\n```plaintext\nKey Files:\n- scripts/complete_update.nu          # All-in-one update script\n- scripts/update_nushell_version.nu   # Nushell update orchestrator\n- scripts/update_all_plugins.nu       # Plugin updater\n- scripts/create_full_distribution.nu # Distribution packager\n- updates/108/                        # Version-specific docs\n- guides/                             # This guide\n\nGenerated Files:\n- updates/108/NUSHELL_0.108_UPDATE_SUMMARY.md\n- updates/108/MIGRATION_0.108.0.md\n- updates/108/VALIDATION_REPORT.md\n- distribution/packages/*.tar.gz\n- bin_archives/*.tar.gz\n```\n\n### Support\n\n**Documentation:**\n\n- This guide: `guides/COMPLETE_VERSION_UPDATE_GUIDE.md`\n- Version docs: `updates/108/`\n- Automation: `updates/108/NUSHELL_UPDATE_AUTOMATION.md`\n- Migration: `updates/108/MIGRATION_0.108.0.md`\n\n**Scripts:**\n\n- `scripts/` - All automation scripts\n- `justfile` - Quick commands\n- `etc/plugin_registry.toml` - Plugin configuration\n\n**Online Resources:**\n\n- [Nushell Book](https://www.nushell.sh/book/)\n- [Plugin Guide](https://www.nushell.sh/book/plugins.html)\n- [GitHub Releases](https://github.com/nushell/nushell/releases)\n\n---\n\n**Guide Version**: 1.0\n**Last Updated**: 2025-10-18\n**Next Review**: With Nushell 0.109.0 release