Plugin Exclusion Guide\n\n## Quick Reference\n\nWhat is plugin exclusion?: A mechanism to prevent certain plugins (like nu_plugin_example) from being included in distributions and installations, while keeping them available for development and testing.\n\nWho should read this?:\n\n- 📦 Release managers\n- 👨💻 Plugin developers\n- 🔧 Maintainers\n- 📚 Users who want to understand the distribution process\n\n---\n\n## Quick Start\n\n### For Users\n\nQuestion: I found nu_plugin_example but it's not in my installation. Why?\n\nAnswer: The example plugin is intentionally excluded from distributions. It's a reference implementation for plugin developers, not a user-facing tool.\n\nIf you want to use it:\n\n1. Clone the repository\n2. Build it: just build\n3. Use the binary directly: ./nushell/target/release/nu_plugin_example\n\n---\n\n### For Developers\n\nQuestion: I want to exclude my plugin from distributions. How?\n\nAnswer: Add it to the exclusion list in etc/plugin_registry.toml:\n\ntoml\n[distribution]\nexcluded_plugins = [\n "nu_plugin_example",\n "nu_plugin_my_new_plugin" # ← Add your plugin here\n]\n\n\nThat's it! The collection and packaging systems will automatically skip it.\n\n---\n\n### For Release Managers\n\nChecklist before release:\n\n1. Verify exclusion list is correct:\n\n bash\n nu -c "open ./etc/plugin_registry.toml | get distribution.excluded_plugins"\n \n\n2. Verify collection respects it:\n\n bash\n just collect\n find distribution -name "*example*" # Should find nothing\n \n\n3. Verify packaging respects it:\n\n bash\n just pack-full\n tar -tzf bin_archives/*.tar.gz | grep example # Should find nothing\n \n\n4. Verify builds still include everything (for testing):\n\n bash\n just build\n ls nushell/target/release/ | grep example # Should find the binary\n \n\n---\n\n## Common Tasks\n\n### Task 1: Add a Plugin to Exclusion List\n\nScenario: You have a new reference plugin that shouldn't be shipped to users.\n\nSteps:\n\n1. Create your plugin in nushell/crates/nu_plugin_myref/\n2. Update etc/plugin_registry.toml:\n\n toml\n [distribution]\n excluded_plugins = [\n "nu_plugin_example",\n "nu_plugin_myref" # ← Add here\n ]\n \n\n3. Update scripts/templates/default_config.nu - remove it from the plugin_binaries list if it was there\n4. Test:\n\n bash\n just collect && find distribution -name "*myref*" # Should be empty\n \n\n---\n\n### Task 2: Remove a Plugin from Exclusion List\n\nScenario: Your reference plugin is now stable and ready for distribution.\n\nSteps:\n\n1. Update etc/plugin_registry.toml:\n\n toml\n [distribution]\n excluded_plugins = [\n "nu_plugin_example" # ← Removed your plugin\n ]\n \n\n2. Update scripts/templates/default_config.nu - add it to the plugin_binaries list if you want auto-loading\n3. Test:\n\n bash\n just collect && find distribution -name "*myref*" # Should exist now\n \n\n---\n\n### Task 3: Check Current Build Includes Excluded Plugin\n\nScenario: You want to verify that excluded plugins are still being built.\n\nSteps:\n\nbash\n# Build everything including excluded plugins\njust build\n\n# Verify excluded plugin was built\nls nushell/target/release/nu_plugin_example\n# Output: nushell/target/release/nu_plugin_example\n\n\nWhy? Excluded plugins are still useful for:\n\n- Testing and validation\n- Reference implementations\n- Developer documentation\n- Internal reference\n\n---\n\n### Task 4: Understand Distribution Workflow\n\nScenario: You want to understand how plugins flow through the build/collect/package process.\n\nDiagram:\n\nplaintext\nSOURCE (all plugins built)\n├── nu_plugin_example (excluded)\n├── nu_plugin_auth\n├── nu_plugin_kms\n└── ... others\n\n ↓ (just build - NO filtering)\n\nBUILD OUTPUT (target/release)\n├── nu_plugin_example ✅ (built)\n├── nu_plugin_auth ✅ (built)\n├── nu_plugin_kms ✅ (built)\n└── ... others ✅ (built)\n\n ↓ (just collect - WITH filtering)\n\nCOLLECTION (distribution/)\n├── nu_plugin_example ❌ (excluded)\n├── nu_plugin_auth ✅ (collected)\n├── nu_plugin_kms ✅ (collected)\n└── ... others ✅ (collected)\n\n ↓ (just pack - WITH filtering)\n\nPACKAGING (bin_archives/)\n├── nushell-0.109.0-linux-x64.tar.gz\n│ ├── nu\n│ ├── nu_plugin_auth ✅\n│ ├── nu_plugin_kms ✅\n│ └── ... (no example plugin)\n└── nushell-0.109.0-darwin-arm64.tar.gz\n ├── nu\n ├── nu_plugin_auth ✅\n ├── nu_plugin_kms ✅\n └── ... (no example plugin)\n\n ↓ (installation)\n\nUSER SYSTEM\n├── ~/.local/bin/nu ✅\n├── ~/.local/bin/nu_plugin_auth ✅\n├── ~/.local/bin/nu_plugin_kms ✅\n├── ~/.config/nushell/env.nu\n└── ~/.config/nushell/config.nu (auto-loads auth, kms; example not in list)\n\n\n---\n\n## Technical Details\n\n### How Exclusion Works\n\nMechanism: The system reads etc/plugin_registry.toml and filters at two points:\n\n1. Collection (just collect / just collect-full):\n - Reads exclusion list from registry\n - Skips excluded plugins during binary collection\n - Result: distribution/ dir doesn't have excluded plugins\n\n2. Packaging (just pack / just pack-full):\n - Reads exclusion list from registry\n - Skips excluded plugins during package creation\n - Result: bin_archives/*.tar.gz don't have excluded plugins\n\n3. Installation (auto-load configuration):\n - scripts/templates/default_config.nu manually removes excluded plugins from the auto-load list\n - Result: User installations don't auto-load excluded plugins\n\n### Files Involved\n\n| File | Role |\n|------|------|\n| etc/plugin_registry.toml | Source of truth for exclusion list |\n| scripts/collect_full_binaries.nu | Implements collection-time filtering |\n| scripts/create_distribution_packages.nu | Implements packaging-time filtering |\n| scripts/templates/default_config.nu | Defines auto-load list (manually edited) |\n| justfile + justfiles/*.just | Provides build/collect/pack commands |\n\n### Registry Format\n\ntoml\n[distribution]\nexcluded_plugins = [\n "nu_plugin_example" # Plugin directory name\n]\nreason = "Reference plugin" # Documentation (optional)\n\n\nKey Points:\n\n- excluded_plugins is a list of plugin directory names (not binary names)\n- Must match the nu_plugin_* directory in the repo\n- Case-sensitive\n- Empty list [] means no exclusions\n\n---\n\n## Troubleshooting\n\n### Problem: Excluded Plugin Still Appears in Distribution\n\nPossible Causes:\n\n1. Registry file not saved properly\n2. Collection script using cached data\n3. Plugin name mismatch\n\nSolution:\n\nbash\n# Verify registry is correct\nnu -c "open ./etc/plugin_registry.toml | get distribution.excluded_plugins"\n\n# Clean and rebuild\nrm -rf distribution bin_archives\njust collect\nfind distribution -name "*example*" # Should be empty\n\n\n---\n\n### Problem: Can't Find Excluded Plugin After Build\n\nExpected Behavior: Excluded plugins ARE still built (just not distributed)\n\nVerification:\n\nbash\njust build\nls nushell/target/release/nu_plugin_example # Should exist\n\n# If it doesn't, the plugin may not be in the build system\njust build-nushell --verbose\n\n\n---\n\n### Problem: Manual Plugin Registration Failing\n\nIssue: User manually adds excluded plugin but it doesn't work\n\nCause: Plugin binary not in PATH\n\nSolution:\n\nbash\n# Build the plugin\njust build\n\n# Use full path\n./nushell/target/release/nu_plugin_example --version\n\n# Or install it manually\ncp ./nushell/target/release/nu_plugin_example ~/.local/bin/\nnu -c "plugin add ~/.local/bin/nu_plugin_example"\n\n\n---\n\n## FAQs\n\nQ: Will my excluded plugin still be tested?\nA: Yes. Excluded plugins are still built and tested. They're only excluded from user-facing distributions.\n\nQ: Can I exclude a plugin from builds but not distributions?\nA: No, the current system doesn't support this. The exclusion system only affects distribution. To exclude from builds, use Cargo features.\n\nQ: Can different distributions have different exclusion lists?\nA: Not currently, but this is planned as a future enhancement (profile-based exclusions).\n\nQ: What happens if I exclude a plugin that doesn't exist?\nA: It's ignored. The filtering works by checking if a plugin name is in the exclusion list, so non-existent plugins are silently skipped.\n\nQ: Can I exclude plugins selectively (e.g., exclude from macOS but not Linux)?\nA: Not currently. This would require platform-based exclusion profiles (future enhancement).\n\n---\n\n## Best Practices\n\n### ✅ DO\n\n- Update the comment in config when excluding/including plugins\n- Test after changes: just collect && just pack-full && just build\n- Document the reason in plugin_registry.toml (optional but recommended)\n- Run verification before releases (see Release Manager checklist)\n- Keep registry clean - don't exclude plugins you won't maintain\n\n### ❌ DON'T\n\n- Edit multiple files - only touch etc/plugin_registry.toml for the core change\n- Assume exclusion happens at build time - it only happens during collect/pack\n- Forget to test - exclusion changes should be verified before release\n- Add plugins to exclusion list without documenting why in the code\n- Exclude plugins that users depend on - use this only for reference/experimental plugins\n\n---\n\n## Integration with CI/CD\n\n### GitHub Actions Example\n\nyaml\nname: Distribution Release\n\non:\n push:\n tags:\n - 'v*'\n\njobs:\n release:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n\n # Verify exclusion list\n - name: Verify Exclusion List\n run: |\n nu -c "open ./etc/plugin_registry.toml | get distribution.excluded_plugins"\n\n # Build (includes all plugins)\n - name: Build\n run: just build-full-release\n\n # Collect (excludes specified plugins)\n - name: Collect\n run: just collect-full\n\n # Verify excluded plugins not in distribution\n - name: Verify Exclusions\n run: |\n ! find distribution -name "*example*"\n\n # Package\n - name: Package\n run: just pack-full-checksums\n\n # Release\n - name: Create Release\n uses: softprops/action-gh-release@v1\n with:\n files: bin_archives/*\n\n\n---\n\n## See Also\n\n- Architecture Details: docs/architecture/plugin-exclusion-system.md\n- Build System: docs/building.md\n- Plugin Development: nushell/crates/nu_plugin_example/ (reference implementation)\n- Registry Configuration: etc/plugin_registry.toml\n\n---\n\nVersion: 1.0.0\nLast Updated: 2025-12-03\nStatus: Stable
d9ef2f0d5b