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](#overview)
2. [Quick Start](#quick-start)
3. [Complete Update Workflow](#complete-update-workflow)
4. [Plugin Updates](#plugin-updates)
5. [Distribution Creation](#distribution-creation)
6. [Troubleshooting](#troubleshooting)
7. [Reference](#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:**

```bash
# 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:**

```bash
# 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

```bash
# Check current nushell version
nu --version

# Check git status
git status

# Check for uncommitted changes
git diff --stat
```

#### 1.2 Create Backup

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Check git status
git status

# Review diffs
git diff

# Check modified files
git diff --name-only
```

#### 6.2 Create Commit

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
# 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:**

```bash
# 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:**

```bash
# 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:

```bash
# 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

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

**Symptom**: Missing system dependencies

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](https://www.nushell.sh/book/)
- [Plugin Guide](https://www.nushell.sh/book/plugins.html)
- [GitHub Releases](https://github.com/nushell/nushell/releases)

---

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