nushell-plugins/guides/README.md

# Nushell Plugins - Guides Directory

**Comprehensive guides for nushell plugin development and version management**

---

## 📚 Available Guides

### 🚀 Quick Start

**[QUICK_START.md](QUICK_START.md)** - Fast track to updating Nushell and creating distributions

**Perfect for**: Getting started immediately, common workflows, quick reference

**Key topics**:
- One-liner updates
- Creating distributions and bin archives
- Common workflows
- Status commands
- Troubleshooting

---

### 📖 Complete Version Update Guide

**[COMPLETE_VERSION_UPDATE_GUIDE.md](COMPLETE_VERSION_UPDATE_GUIDE.md)** - Comprehensive guide for updating Nushell versions

**Perfect for**: Understanding the complete update process, step-by-step instructions

**Key topics**:
- Complete update workflow (all phases)
- Plugin updates
- Distribution creation
- Validation and testing
- Troubleshooting
- Reference commands

---

## 🗂️ Version-Specific Documentation

Version-specific documentation is located in the `updates/` directory:

```
updates/
├── 107/              # Nushell 0.107.x documentation
├── 108/              # Nushell 0.108.x documentation
│   ├── NUSHELL_0.108_UPDATE_SUMMARY.md       # Complete update summary
│   ├── MIGRATION_0.108.0.md                  # Migration guide
│   ├── NUSHELL_UPDATE_AUTOMATION.md          # Automation documentation
│   └── ... (validation reports, change logs)
└── 109/              # Future versions...
```

---

## 🎯 Quick Navigation

### I want to...

**...update to a new Nushell version**
→ Read: [QUICK_START.md](QUICK_START.md#one-liner-update)
→ Run: `just complete-update 0.108.0`

**...create distribution packages**
→ Read: [QUICK_START.md](QUICK_START.md#how-do-i-create-distributions-and-bin_archives)
→ Run: `just create-distribution`

**...update only plugins**
→ Read: [QUICK_START.md](QUICK_START.md#workflow-2-update-only-plugins)
→ Run: `just update-plugins 0.108.0`

**...understand the complete process**
→ Read: [COMPLETE_VERSION_UPDATE_GUIDE.md](COMPLETE_VERSION_UPDATE_GUIDE.md)

**...check migration requirements**
→ Read: `updates/108/MIGRATION_0.108.0.md`

**...understand the automation**
→ Read: `updates/108/NUSHELL_UPDATE_AUTOMATION.md`

---

## 🔧 Command Quick Reference

### Update Commands

```bash
# Complete update
just complete-update 0.108.0          # All-in-one
just update-latest                     # Latest version

# Step-by-step
just update-nushell 0.108.0           # Nushell core only
just update-plugins 0.108.0           # Plugins only
just create-distribution              # Distributions only
```

### Status Commands

```bash
just update-status                    # Update system status
just dist-status                      # Distribution status
just check-versions                   # Version consistency
just list-versions                    # List plugin versions
just audit-deps                       # Dependency audit
```

### Help Commands

```bash
just update-help                      # Quick command reference
just update-docs                      # Documentation paths
just help                            # All available commands
```

---

## 📖 Documentation Structure

```
Repository Documentation:
├── guides/                           # This directory
│   ├── README.md                     # This file
│   ├── QUICK_START.md                # Fast track guide
│   └── COMPLETE_VERSION_UPDATE_GUIDE.md  # Complete guide
│
├── updates/                          # Version-specific docs
│   ├── 107/
│   ├── 108/
│   │   ├── NUSHELL_0.108_UPDATE_SUMMARY.md
│   │   ├── MIGRATION_0.108.0.md
│   │   ├── NUSHELL_UPDATE_AUTOMATION.md
│   │   └── ... (validation, changes, etc.)
│   └── 109/
│
├── README.md                         # Repository overview
├── CHANGELOG.md                      # All changes
├── CLAUDE.md                         # Claude Code guidance
│
└── scripts/                          # Automation scripts
    ├── complete_update.nu            # All-in-one updater
    ├── update_all_plugins.nu         # Bulk plugin updater
    ├── create_full_distribution.nu   # Distribution creator
    └── ... (8 total update scripts)
```

---

## 🎓 Learning Path

### For First-Time Users

1. **Start here**: [QUICK_START.md](QUICK_START.md)
   - Learn the one-liner update command
   - Understand what gets created

2. **Then read**: Repository README.md
   - Understand repository structure
   - Learn about plugin types

3. **For deeper knowledge**: [COMPLETE_VERSION_UPDATE_GUIDE.md](COMPLETE_VERSION_UPDATE_GUIDE.md)
   - Complete workflow understanding
   - Troubleshooting guide

### For Experienced Users

1. **Quick Reference**: [QUICK_START.md](QUICK_START.md)
   - Command cheat sheet
   - Common workflows

2. **Automation Details**: `updates/108/NUSHELL_UPDATE_AUTOMATION.md`
   - How automation works
   - Customization options

3. **Version Changes**: `updates/108/MIGRATION_0.108.0.md`
   - Breaking changes
   - Migration steps

---

## 💡 Tips & Best Practices

### Before Updating

✅ Always check for breaking changes:
```bash
just detect-breaking
```

✅ Create a backup:
```bash
git stash save "backup before update"
```

✅ Check current versions:
```bash
just check-versions
just audit-deps
```

### During Update

✅ Use the all-in-one command for simplicity:
```bash
just complete-update 0.108.0
```

✅ Monitor progress:
```bash
just update-status
```

### After Update

✅ Validate everything works:
```bash
just validate-code
just verify-plugins
```

✅ Create distributions:
```bash
just create-distribution-all
```

✅ Commit changes:
```bash
git add -A
git commit -m "chore: update to Nushell 0.108.0"
```

---

## 🆘 Getting Help

### Quick Help

```bash
# Show all update commands
just update-help

# Show documentation paths
just update-docs

# Show all available commands
just help
```

### Documentation

- **This file**: Overview and navigation
- **QUICK_START.md**: Fast track and common workflows
- **COMPLETE_VERSION_UPDATE_GUIDE.md**: Comprehensive guide
- **updates/108/**: Version-specific documentation

### Online Resources

- [Nushell Book](https://www.nushell.sh/book/)
- [Plugin Development](https://www.nushell.sh/book/plugins.html)
- [GitHub Releases](https://github.com/nushell/nushell/releases)

---

## 🔄 Update Workflow Summary

```mermaid
graph TD
    A[Start: New Nushell Version] --> B{Choose Workflow}
    B -->|All-in-One| C[just complete-update 0.108.0]
    B -->|Step-by-Step| D[just update-nushell 0.108.0]

    C --> Z[Done! ✅]

    D --> E[just update-plugins 0.108.0]
    E --> F[just create-distribution]
    F --> G[just validate-code]
    G --> Z

    Z --> H[Commit Changes]
    H --> I[Push to Repository]
```

---

**Last Updated**: 2025-10-18
**Current Nushell Version**: 0.108.0
**Guides Status**: ✅ Complete and ready to use