nushell-plugins/updates/109/MIGRATION_0.109.0.md

Migration Guide: Nushell 0.109.0

Date: 2025-11-30 From: 0.108.0 To: 0.109.0

Overview

This guide covers the migration of all 13 plugins from Nushell 0.108.0 to 0.109.0, including the improvements made to the version update system.

What You Need to Know

Version Management Changes

Smart Version Detection (NEW)

The update process now uses intelligent version management:

1. Dependency Versions: Always synchronized with Nushell version (all plugins get 0.109.0)
2. Package Versions: Only updated for plugins that tracked Nushell versions
3. Independent Versions: Preserved for plugins with their own versioning

Example:

# Before 0.109.0 update
[package]
version = "0.108.0"        # Tracks Nushell version

[dependencies]
nu-plugin = "0.108.0"      # Gets updated

# After 0.109.0 update
[package]
version = "0.109.0"        # Updated because it was 0.108.0
nu-plugin = "0.109.0"      # Always updated

Script Improvements

1. String Interpolation Fix (Rule 18 Compliance)

Before:

log_info $"(DRY RUN) Would update ($p.name)"  # ❌ Error: DRY is not a command

After:

log_info $"\(DRY RUN\) Would update ($p.name)"  # ✅ Correct: escaped parentheses

2. Template Generation Fix

Before:

# Generated incorrect filename
install_script | save --force $"($target_path)/install.nu"  # ❌ Wrong name

After:

# Correctly generates register-plugins.nu
install_script | save --force $"($target_path)/register-plugins.nu"  # ✅ Correct

Reason:

• install.sh - Installs binaries to filesystem
• register-plugins.nu - Registers plugins with Nushell (doesn't install binaries)

3. Bootstrap Auto-Detection

Before:

# Had to manually specify source path
./install.sh --source-path ./bin

After:

# Automatically detects local binaries
./install.sh  # ✅ Auto-detects ./bin/nu or ./nu

Updated Plugins

Package Version Updated

• nu_plugin_clipboard: 0.108.0 → 0.109.0
  • Had previous Nushell version, so it was automatically updated
  • All 13 plugins still have nu-plugin = 0.109.0 dependency

Package Versions Preserved

All other plugins kept their own versions:

• nu_plugin_auth: 0.1.0 (custom version)
• nu_plugin_desktop_notifications: 1.2.12 (custom version)
• nu_plugin_fluent: 0.1.0 (custom version)
• nu_plugin_hashes: 0.1.8 (custom version)
• nu_plugin_highlight: 1.4.7+0.105.2 (custom version)
• nu_plugin_image: 0.105.1 (custom version)
• nu_plugin_kcl: 0.1.0 (custom version)
• nu_plugin_kms: 0.1.0 (custom version)
• nu_plugin_orchestrator: 0.1.0 (custom version)
• nu_plugin_port_extension: 0.109.0 (already at Nushell version)
• nu_plugin_qr_maker: 1.1.0 (custom version)
• nu_plugin_tera: 0.1.0 (custom version)

Backward Compatibility

For Future Updates

When updating to 0.110.0 or later, the system will:

1. Calculate the previous version automatically (0.109.0 in this case)
2. Only update plugins that have version = 0.109.0
3. Preserve all independent versions

Example for 0.110.0 update:

# Plugin versions with 0.109.0 would become 0.110.0
# Others would stay as-is

Breaking Changes

None - All plugins are backward compatible with 0.109.0

Deprecations

None - All functionality is preserved

Installation & Registration

New Workflow

# 1. Install binaries
cd distribution/darwin-arm64
./install.sh

# 2. Register plugins with Nushell (doesn't install, just registers)
nu register-plugins.nu

# 3. Verify installation
nu -c 'plugin list'

Old Workflow (Before)

The install.sh script now handles both binary installation and has better auto-detection.

Performance Impact

• None - All plugins compile to equivalent binaries
• Build times may vary based on system load
• No runtime performance changes

Troubleshooting

Issue: "plugin list" shows old version

Solution: Rebuild and re-register

just build
nu register-plugins.nu

Issue: "DRY RUN error" when running update script

Solution: This is fixed in 0.109.0. Ensure you have the latest scripts.

Issue: install.sh doesn't auto-detect binaries

Solution: Ensure you have the latest installers/bootstrap/install.sh

Files Changed

Modified Scripts

• scripts/update_all_plugins.nu - Smart version detection
• scripts/collect_full_binaries.nu - Correct template generation
• scripts/complete_update.nu - Updated documentation
• scripts/create_full_distribution.nu - Updated documentation
• installers/bootstrap/install.sh - Auto-detection added

Modified Documentation

• CLAUDE.md - Version updated to 0.109.0

Plugin Updates

• nu_plugin_clipboard/Cargo.toml - Version 0.108.0 → 0.109.0

Validation Checklist

• All 13 plugins compile successfully
• All plugins have nu-plugin = 0.109.0 dependency
• Package versions are correctly handled (1 updated, 12 preserved)
• Scripts work without string interpolation errors
• Templates generate correct filenames
• Bootstrap installer auto-detects local binaries
• Plugin registration works correctly
• Distribution packages are complete

Next Steps

1. Review the update summary: updates/109/UPDATE_SUMMARY.md
2. Build plugins: just build
3. Test: just test
4. Create distribution: just pack-full
5. Review changes and commit when ready

Questions or Issues?

Refer to:

• CLAUDE.md - Project guidelines and setup
• guides/COMPLETE_VERSION_UPDATE_GUIDE.md - Complete update procedures
• updates/109/UPDATE_SUMMARY.md - What changed in this update