4b92aa764a
Some checks failed
Build and Test / Validate Setup (push) Has been cancelled
Build and Test / Build (darwin-amd64) (push) Has been cancelled
Build and Test / Build (darwin-arm64) (push) Has been cancelled
Build and Test / Build (linux-amd64) (push) Has been cancelled
Build and Test / Build (windows-amd64) (push) Has been cancelled
Build and Test / Build (linux-arm64) (push) Has been cancelled
Build and Test / Security Audit (push) Has been cancelled
Build and Test / Package Results (push) Has been cancelled
Build and Test / Quality Gate (push) Has been cancelled
279 lines
8.5 KiB
Markdown
279 lines
8.5 KiB
Markdown
# Architecture Documentation
|
|
|
|
Welcome to the architecture documentation for the nushell-plugins project. This directory contains Architecture Decision Records (ADRs), design documents, and technical guides.
|
|
|
|
---
|
|
|
|
## Architecture Decision Records (ADRs)
|
|
|
|
### [ADR-001: Plugin Exclusion System](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md)
|
|
|
|
**Status**: ✅ Accepted & Implemented
|
|
**Date**: 2025-12-03
|
|
|
|
A configuration-driven system for excluding reference/documentation plugins from distributions while keeping them available for development and testing.
|
|
|
|
**Key Points**:
|
|
- Single source of truth in `etc/plugin_registry.toml`
|
|
- Non-breaking - doesn't affect builds, tests, or development
|
|
- Centralized filtering at collection and packaging stages
|
|
- Foundation for future profile-based and conditional exclusions
|
|
|
|
**When to Read**: If you want to understand WHY the exclusion system was implemented and how design decisions were made.
|
|
|
|
---
|
|
|
|
## Technical Specifications
|
|
|
|
### [Plugin Exclusion System - Technical Architecture](./PLUGIN_EXCLUSION_SYSTEM.md)
|
|
|
|
**Status**: ✅ Complete
|
|
**Version**: 1.0.0
|
|
|
|
Deep-dive into the technical implementation of plugin exclusions, including:
|
|
- How the system works under the hood
|
|
- Code implementation details
|
|
- Error handling and resilience
|
|
- Integration points with build/collect/package workflows
|
|
- Performance impact analysis
|
|
- Future enhancement possibilities
|
|
|
|
**Sections**:
|
|
- Overview and design principles
|
|
- Configuration details
|
|
- Implementation in collection system
|
|
- Implementation in packaging system
|
|
- Implementation in installation configuration
|
|
- Behavior matrix (what happens in each scenario)
|
|
- Use cases and examples
|
|
- Error handling strategies
|
|
- Maintenance procedures
|
|
- Testing and verification
|
|
|
|
**When to Read**: If you need to understand HOW the system works, maintain it, or extend it.
|
|
|
|
---
|
|
|
|
## Guides & Documentation
|
|
|
|
### [Plugin Exclusion Guide - Quick Reference & Troubleshooting](../PLUGIN_EXCLUSION_GUIDE.md)
|
|
|
|
**Status**: ✅ Complete
|
|
**Version**: 1.0.0
|
|
|
|
User-friendly guide covering:
|
|
- Quick reference for different user types
|
|
- Common tasks (add/remove exclusions, verify builds, etc.)
|
|
- Technical details for developers
|
|
- Troubleshooting section
|
|
- FAQs
|
|
- Best practices
|
|
- CI/CD integration examples
|
|
|
|
**Sections**:
|
|
- Quick start for users, developers, and release managers
|
|
- Common tasks with step-by-step instructions
|
|
- Technical workflow diagrams
|
|
- Troubleshooting guide
|
|
- FAQs
|
|
- Best practices (DO/DON'T)
|
|
- CI/CD integration examples
|
|
|
|
**When to Read**: If you're learning the system, performing a task related to exclusions, or troubleshooting issues.
|
|
|
|
---
|
|
|
|
## Navigation Guide
|
|
|
|
### By User Role
|
|
|
|
**👤 End Users**:
|
|
Start with: [Plugin Exclusion Guide - Quick Start (Users)](../PLUGIN_EXCLUSION_GUIDE.md#for-users)
|
|
- Explains why some plugins aren't in distributions
|
|
- Shows how to access excluded plugins if needed
|
|
|
|
**👨💻 Plugin Developers**:
|
|
Start with: [Plugin Exclusion Guide - Quick Start (Developers)](../PLUGIN_EXCLUSION_GUIDE.md#for-developers)
|
|
Then read: [Technical Architecture](./PLUGIN_EXCLUSION_SYSTEM.md)
|
|
- How to exclude your plugin during development
|
|
- How the filtering system works
|
|
- Implementation details
|
|
|
|
**📦 Release Managers**:
|
|
Start with: [Plugin Exclusion Guide - Release Checklist](../PLUGIN_EXCLUSION_GUIDE.md#for-release-managers)
|
|
Then read: [ADR-001](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md)
|
|
- Pre-release verification steps
|
|
- How to test exclusions
|
|
- Decision rationale for documentation
|
|
|
|
**🔧 Maintainers/Architects**:
|
|
Start with: [ADR-001](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md)
|
|
Then read: [Technical Architecture](./PLUGIN_EXCLUSION_SYSTEM.md)
|
|
- Design decisions and trade-offs
|
|
- Implementation details
|
|
- Extension points for future enhancements
|
|
|
|
### By Task
|
|
|
|
**"I want to exclude a plugin"**:
|
|
→ [Plugin Exclusion Guide - Task 1](../PLUGIN_EXCLUSION_GUIDE.md#task-1-add-a-plugin-to-exclusion-list)
|
|
|
|
**"I want to remove a plugin from exclusion"**:
|
|
→ [Plugin Exclusion Guide - Task 2](../PLUGIN_EXCLUSION_GUIDE.md#task-2-remove-a-plugin-from-exclusion-list)
|
|
|
|
**"I need to understand the workflow"**:
|
|
→ [Plugin Exclusion Guide - Task 4](../PLUGIN_EXCLUSION_GUIDE.md#task-4-understand-distribution-workflow)
|
|
|
|
**"Something isn't working"**:
|
|
→ [Plugin Exclusion Guide - Troubleshooting](../PLUGIN_EXCLUSION_GUIDE.md#troubleshooting)
|
|
|
|
**"I need to extend the system"**:
|
|
→ [Technical Architecture - Future Enhancements](./PLUGIN_EXCLUSION_SYSTEM.md#future-enhancements)
|
|
|
|
**"I need to integrate with CI/CD"**:
|
|
→ [Plugin Exclusion Guide - CI/CD Integration](../PLUGIN_EXCLUSION_GUIDE.md#integration-with-cicd)
|
|
|
|
---
|
|
|
|
## File Organization
|
|
|
|
```
|
|
docs/
|
|
├── README.md (this file)
|
|
├── BUILDING.md
|
|
├── PLUGIN_EXCLUSION_GUIDE.md ← User guide & troubleshooting
|
|
├── PROVISIONING_PLUGINS_SUMMARY.md
|
|
└── architecture/
|
|
├── README.md ← You are here
|
|
├── ADR-001-PLUGIN_EXCLUSION_SYSTEM.md ← Decision record
|
|
└── PLUGIN_EXCLUSION_SYSTEM.md ← Technical spec
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Links
|
|
|
|
| Document | Purpose | Read Time |
|
|
|----------|---------|-----------|
|
|
| [Plugin Exclusion Guide](../PLUGIN_EXCLUSION_GUIDE.md) | Practical how-to's | 15 min |
|
|
| [Technical Architecture](./PLUGIN_EXCLUSION_SYSTEM.md) | Deep technical details | 30 min |
|
|
| [ADR-001](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md) | Decision & rationale | 20 min |
|
|
|
|
---
|
|
|
|
## Key Concepts
|
|
|
|
### Plugin Exclusion
|
|
Mechanism to prevent certain plugins (typically reference implementations) from being included in distributions and installations, while keeping them available for development, testing, and reference purposes.
|
|
|
|
**Key Points**:
|
|
- Controlled by `etc/plugin_registry.toml`
|
|
- Affects ONLY collection and packaging (not build)
|
|
- Used for reference plugins, experimental features, internal tools
|
|
- Does NOT prevent building or testing
|
|
|
|
### Distribution Pipeline
|
|
```
|
|
Source Code
|
|
↓ (just build)
|
|
Build Output (all plugins)
|
|
↓ (just collect)
|
|
Collection (filtered)
|
|
↓ (just pack)
|
|
Packages (filtered)
|
|
↓ (install)
|
|
User Systems (filtered)
|
|
```
|
|
|
|
### Filtering Points
|
|
1. **Collection** - skips excluded when collecting binaries
|
|
2. **Packaging** - skips excluded when creating archives
|
|
3. **Configuration** - config template doesn't auto-load excluded
|
|
4. **NOT at Build** - all plugins still built for testing
|
|
|
|
---
|
|
|
|
## System Components
|
|
|
|
### Configuration (`etc/plugin_registry.toml`)
|
|
Source of truth for which plugins are excluded from distributions.
|
|
|
|
**Example**:
|
|
```toml
|
|
[distribution]
|
|
excluded_plugins = [
|
|
"nu_plugin_example"
|
|
]
|
|
reason = "Reference implementation"
|
|
```
|
|
|
|
### Collection System (`scripts/collect_full_binaries.nu`)
|
|
Gathers built binaries for distribution, excluding specified plugins.
|
|
|
|
**Functions**:
|
|
- `get_excluded_plugins()` - loads exclusion list
|
|
- `get_workspace_plugins_info()` - filters workspace plugins
|
|
- `get_custom_plugins_info()` - filters custom plugins
|
|
|
|
### Packaging System (`scripts/create_distribution_packages.nu`)
|
|
Creates distribution archives, excluding specified plugins.
|
|
|
|
**Functions**:
|
|
- `get_excluded_plugins_dist()` - loads exclusion list
|
|
- `get_plugin_components()` - filters plugin components
|
|
|
|
### Installation Configuration (`scripts/templates/default_config.nu`)
|
|
Default Nushell configuration that doesn't auto-load excluded plugins.
|
|
|
|
---
|
|
|
|
## Testing & Verification
|
|
|
|
### Basic Verification
|
|
```bash
|
|
# Check exclusion list is readable
|
|
nu -c "open ./etc/plugin_registry.toml | get distribution.excluded_plugins"
|
|
|
|
# Verify collection excludes properly
|
|
just collect
|
|
find distribution -name "*example*" # Should be empty
|
|
|
|
# Verify packaging excludes properly
|
|
just pack-full
|
|
tar -tzf bin_archives/*.tar.gz | grep example # Should be empty
|
|
|
|
# Verify builds still include everything
|
|
just build
|
|
ls nushell/target/release/nu_plugin_example # Should exist
|
|
```
|
|
|
|
### Release Verification
|
|
See [Plugin Exclusion Guide - Release Checklist](../PLUGIN_EXCLUSION_GUIDE.md#for-release-managers) for complete pre-release checklist.
|
|
|
|
---
|
|
|
|
## Contact & Questions
|
|
|
|
For questions about:
|
|
- **Usage**: See [Plugin Exclusion Guide](../PLUGIN_EXCLUSION_GUIDE.md)
|
|
- **Design**: See [ADR-001](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md)
|
|
- **Implementation**: See [Technical Architecture](./PLUGIN_EXCLUSION_SYSTEM.md)
|
|
- **Issues**: Check the project issue tracker
|
|
|
|
---
|
|
|
|
## Version Information
|
|
|
|
| Component | Version | Updated |
|
|
|-----------|---------|---------|
|
|
| ADR-001 | 1.0 | 2025-12-03 |
|
|
| Technical Spec | 1.0 | 2025-12-03 |
|
|
| User Guide | 1.0 | 2025-12-03 |
|
|
| System | v1.0.0 | 2025-12-03 |
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-12-03
|
|
**Status**: Complete & Stable
|
|
**Maintainer**: Project Team
|