# Nushell 0.108.0 Documentation Summary

This directory contains comprehensive documentation for Nushell 0.108.0 breaking changes, new features, and migration guides.

## Files in This Documentation Set

### 1. NUSHELL_0.108.0_CHANGES.md
**Comprehensive markdown documentation** covering all changes in Nushell 0.108.0.

**Contents:**
- Complete breaking changes with migration guides
- All new features and enhancements
- Experimental features (pipefail, enforce-runtime-annotations, reorder-cell-paths)
- Plugin API changes and CustomValue improvements
- Command changes (renamed, removed, added, modified)
- Behavior changes and bug fixes
- Build system changes
- Best practices and recommendations

**Use this file for:**
- Human-readable reference documentation
- Migration planning
- Understanding impact of changes
- Learning new features

### 2. nushell_0.108.0_changes.nu
**Structured Nushell data file** with all changes in programmatic format.

**Contents:**
- Complete structured record with all version 0.108.0 data
- Helper functions to access specific data:
  - `get-changes` - Get complete dataset
  - `get-breaking-changes` - Get all breaking changes
  - `get-high-impact-changes` - Filter high impact changes only
  - `get-new-features` - Get new features list
  - `get-experimental-features` - Get experimental features
  - `get-plugin-api-changes` - Get plugin API changes
  - `get-command-changes` - Get command changes
  - `get-recommendations` - Get best practices
  - `search-changes [keyword]` - Search all changes by keyword
  - `generate-migration-report` - Generate formatted migration report

**Use this file for:**
- Automated analysis of changes
- Programmatic migration tools
- Custom reporting
- Integration with CI/CD pipelines

**Example usage:**
```nushell
# Load the module
use nushell_0.108.0_changes.nu *

# Get all breaking changes
get-breaking-changes

# Get only high impact changes
get-high-impact-changes

# Search for specific changes
search-changes "into value"

# Generate migration report
generate-migration-report

# Access specific data
let changes = get-changes
$changes.version
$changes.experimental_features
```

## Quick Reference

### Breaking Changes Summary

1. **`into value` → `detect type`** (HIGH IMPACT)
   - Type detection command renamed
   - `into value` now converts custom plugin values
   - Migration: Use `update cells {detect type}` for table cells

2. **Stream Error Collection** (HIGH IMPACT)
   - Collecting streams with errors now raises errors
   - Migration: Wrap in try-catch blocks

3. **`format bits` Endian** (MEDIUM IMPACT)
   - New `--endian` flag required
   - Migration: Specify endian explicitly

4. **Polars Changes** (MEDIUM IMPACT)
   - `polars fetch` removed
   - `polars pivot` requires `--stable` flag

5. **Windows Paths** (LOW IMPACT, Windows only)
   - UNC paths no longer get trailing backslash
   - Device paths now work with open/save/source

6. **Network Feature Flag** (LOW IMPACT, custom builds only)
   - Must use `--features network` for custom builds

7. **Power Operator** (LOW IMPACT)
   - Now right-associative (mathematically correct)

### New Features Summary

1. **MCP Server for AI Agents** (Optional, compile with `--features mcp`)
2. **Smarter Completions** (Inline completion lists)
3. **Enhanced CustomValue Support** (Plugin API improvements)
4. **`which` Enhancement** (Lists all commands when called without args)
5. **HTTP Metadata** (Response data as metadata)
6. **Date/Time Specifiers** (`%J` and `%Q` for compact formats)
7. **`metadata set --merge`** (Attach arbitrary metadata)
8. **`each --flatten`** (Better streaming)

### Experimental Features

1. **pipefail** (Opt-in) - Bash-like pipeline error handling
2. **enforce-runtime-annotations** (Opt-in) - Runtime type checking
3. **reorder-cell-paths** (Now opt-out/default) - Performance optimization

### Command Changes at a Glance

**Renamed:**
- `into value` → `detect type` (type detection)
- N/A → `into value` (custom value conversion)

**Removed:**
- `polars fetch`

**Added:**
- `detect type`
- `into value` (new purpose)

**Modified:**
- `format bits` - Added `--endian` flag
- `polars pivot` - Added `--stable` flag
- `which` - Lists all commands without args
- `http *` - Metadata attachment
- `format date` / `into datetime` - New specifiers
- `metadata set` - Added `--merge`
- `each` - Added `--flatten`
- `compact` - Improved `--empty`
- `open` / `save` / `source` - Windows device path support

## Migration Priority

### Immediate Actions Required (HIGH)
1. Replace all `into value` with appropriate command:
   - For tables: `update cells {detect type}`
   - For other types: `detect type`
   - For plugin values: Keep as `into value`
2. Add try-catch around stream collections
3. Update `polars` commands if using polars plugin

### Should Address (MEDIUM)
1. Add `--endian` flag to `format bits` calls
2. Update custom builds to include `--features network`
3. Review chained power operations
4. Test on Windows if applicable

### Nice to Have (LOW)
1. Adopt inline completion syntax
2. Use new date/time format specifiers
3. Enable experimental features for testing
4. Update plugin implementations for CustomValue

## Testing Your Migration

```nushell
# 1. Search your codebase for problematic patterns
use nushell_0.108.0_changes.nu *

# Search for 'into value' usage
rg "into value" . --type nu

# Search for 'polars fetch'
rg "polars fetch" . --type nu

# Search for 'format bits' without endian flag
rg "format bits" . --type nu | where ($it !~ "--endian")

# 2. Run tests with experimental features
nu --experimental-options='pipefail,enforce-runtime-annotations' your_tests.nu

# 3. Generate migration report
generate-migration-report | save migration_report.txt
```

## Best Practices for 0.108.0

1. **Error Handling**: Always use try-catch for stream collection
2. **Type Safety**: Enable `enforce-runtime-annotations` in production
3. **Completions**: Use inline syntax for static completions
4. **Endian**: Be explicit with `--endian` flag
5. **Testing**: Test with experimental features enabled
6. **Documentation**: Document required version and features
7. **Future-Proofing**: Write code compatible with experimental features

## Resources

- **Official Release Notes**: https://www.nushell.sh/blog/2025-10-15-nushell_v0_108_0.html
- **GitHub Release**: https://github.com/nushell/nushell/releases/tag/0.108.0
- **Discord Community**: #ai-with-nu (for MCP discussions)
- **Issue Tracking**:
  - Pipefail: #16760
  - Reorder Cell Paths: #16766

## Contributors

Special thanks to all 24 contributors who made this release possible:

@132ikl, @andoalon, @app/dependabot, @ayax79, @Bahex, @blindFS, @cablehead, @cptpiepmatz, @fdncred, @fixerer, @Jan9103, @maxim-uvarov, @mkatychev, @nome, @sgvictorino, @Sheape, @sholderbach, @simonborje, @Tyarel8, @weirdan, @WindSoilder, @xolra0d, @Xylobyte, @ysthakur

## Documentation Maintenance

**Created:** 2025-10-18
**Nushell Version:** 0.108.0
**Previous Version:** 0.107.x
**Maintained By:** Nushell Plugins Repository Team

---

## Quick Start Migration Guide

For most users, these are the critical changes:

1. **Find and replace:**
   ```bash
   # Search for 'into value'
   rg "into value" . --type nu

   # Replace based on context:
   # - Tables: | update cells {detect type}
   # - Other: | detect type
   # - Plugins: | into value (no change)
   ```

2. **Add error handling:**
   ```nushell
   # Before:
   let data = $stream | collect

   # After:
   let data = try { $stream | collect } catch { [] }
   ```

3. **Fix polars commands (if using):**
   ```nushell
   # Remove: polars fetch (no replacement)
   # Update: polars pivot → polars pivot --stable
   ```

4. **Test your code:**
   ```bash
   nu your_script.nu
   ```

That's it! For most users, these four steps will handle the migration to 0.108.0.