be62c8701a
- Add `show-arguments` recipe documenting all version update commands - Add `complete-update-interactive` recipe for manual confirmations - Maintain `complete-update` as automatic mode (no prompts) - Update `update-help` to reference new recipes and modes - Document 7-step workflow and step-by-step differences Changes: - complete-update: Automatic mode (recommended for CI/CD) - complete-update-interactive: Interactive mode (with confirmations) - show-arguments: Complete documentation of all commands and modes - Both modes share same 7-step workflow with different behavior in Step 4
289 lines
6.9 KiB
Markdown
289 lines
6.9 KiB
Markdown
# 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
|