2025-12-11 21:50:42 +00:00
<!DOCTYPE HTML>
< html lang = "en" class = "ayu sidebar-visible" dir = "ltr" >
< head >
<!-- Book generated using mdBook -->
< meta charset = "UTF-8" >
< title > Multi-Repo Strategy - Provisioning Platform Documentation< / title >
<!-- Custom HTML head -->
< meta name = "description" content = "Complete documentation for the Provisioning Platform - Infrastructure automation with Nushell, KCL, and Rust" >
< meta name = "viewport" content = "width=device-width, initial-scale=1" >
< meta name = "theme-color" content = "#ffffff" >
< link rel = "icon" href = "../favicon.svg" >
< link rel = "shortcut icon" href = "../favicon.png" >
< link rel = "stylesheet" href = "../css/variables.css" >
< link rel = "stylesheet" href = "../css/general.css" >
< link rel = "stylesheet" href = "../css/chrome.css" >
< link rel = "stylesheet" href = "../css/print.css" media = "print" >
<!-- Fonts -->
< link rel = "stylesheet" href = "../FontAwesome/css/font-awesome.css" >
< link rel = "stylesheet" href = "../fonts/fonts.css" >
<!-- Highlight.js Stylesheets -->
< link rel = "stylesheet" id = "highlight-css" href = "../highlight.css" >
< link rel = "stylesheet" id = "tomorrow-night-css" href = "../tomorrow-night.css" >
< link rel = "stylesheet" id = "ayu-highlight-css" href = "../ayu-highlight.css" >
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
< script >
const path_to_root = "../";
const default_light_theme = "ayu";
const default_dark_theme = "navy";
< / script >
<!-- Start loading toc.js asap -->
< script src = "../toc.js" > < / script >
< / head >
< body >
< div id = "mdbook-help-container" >
< div id = "mdbook-help-popup" >
< h2 class = "mdbook-help-title" > Keyboard shortcuts< / h2 >
< div >
< p > Press < kbd > ←< / kbd > or < kbd > →< / kbd > to navigate between chapters< / p >
< p > Press < kbd > S< / kbd > or < kbd > /< / kbd > to search in the book< / p >
< p > Press < kbd > ?< / kbd > to show this help< / p >
< p > Press < kbd > Esc< / kbd > to hide this help< / p >
< / div >
< / div >
< / div >
< div id = "body-container" >
<!-- Work around some values being stored in localStorage wrapped in quotes -->
< script >
try {
let theme = localStorage.getItem('mdbook-theme');
let sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') & & theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') & & sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
< / script >
<!-- Set the theme before any content is loaded, prevents flash -->
< script >
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('ayu')
html.classList.add(theme);
html.classList.add("js");
< / script >
< input type = "checkbox" id = "sidebar-toggle-anchor" class = "hidden" >
<!-- Hide / unhide sidebar before it is displayed -->
< script >
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
< / script >
< nav id = "sidebar" class = "sidebar" aria-label = "Table of contents" >
<!-- populated by js -->
< mdbook-sidebar-scrollbox class = "sidebar-scrollbox" > < / mdbook-sidebar-scrollbox >
< noscript >
< iframe class = "sidebar-iframe-outer" src = "../toc.html" > < / iframe >
< / noscript >
< div id = "sidebar-resize-handle" class = "sidebar-resize-handle" >
< div class = "sidebar-resize-indicator" > < / div >
< / div >
< / nav >
< div id = "page-wrapper" class = "page-wrapper" >
< div class = "page" >
< div id = "menu-bar-hover-placeholder" > < / div >
< div id = "menu-bar" class = "menu-bar sticky" >
< div class = "left-buttons" >
< label id = "sidebar-toggle" class = "icon-button" for = "sidebar-toggle-anchor" title = "Toggle Table of Contents" aria-label = "Toggle Table of Contents" aria-controls = "sidebar" >
< i class = "fa fa-bars" > < / i >
< / label >
< button id = "theme-toggle" class = "icon-button" type = "button" title = "Change theme" aria-label = "Change theme" aria-haspopup = "true" aria-expanded = "false" aria-controls = "theme-list" >
< i class = "fa fa-paint-brush" > < / i >
< / button >
< ul id = "theme-list" class = "theme-popup" aria-label = "Themes" role = "menu" >
< li role = "none" > < button role = "menuitem" class = "theme" id = "default_theme" > Auto< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "light" > Light< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "rust" > Rust< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "coal" > Coal< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "navy" > Navy< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "ayu" > Ayu< / button > < / li >
< / ul >
< button id = "search-toggle" class = "icon-button" type = "button" title = "Search (`/`)" aria-label = "Toggle Searchbar" aria-expanded = "false" aria-keyshortcuts = "/ s" aria-controls = "searchbar" >
< i class = "fa fa-search" > < / i >
< / button >
< / div >
< h1 class = "menu-title" > Provisioning Platform Documentation< / h1 >
< div class = "right-buttons" >
< a href = "../print.html" title = "Print this book" aria-label = "Print this book" >
< i id = "print-button" class = "fa fa-print" > < / i >
< / a >
< a href = "https://github.com/provisioning/provisioning-platform" title = "Git repository" aria-label = "Git repository" >
< i id = "git-repository-button" class = "fa fa-github" > < / i >
< / a >
< a href = "https://github.com/provisioning/provisioning-platform/edit/main/provisioning/docs/src/architecture/multi-repo-strategy.md" title = "Suggest an edit" aria-label = "Suggest an edit" >
< i id = "git-edit-button" class = "fa fa-edit" > < / i >
< / a >
< / div >
< / div >
< div id = "search-wrapper" class = "hidden" >
< form id = "searchbar-outer" class = "searchbar-outer" >
< input type = "search" id = "searchbar" name = "searchbar" placeholder = "Search this book ..." aria-controls = "searchresults-outer" aria-describedby = "searchresults-header" >
< / form >
< div id = "searchresults-outer" class = "searchresults-outer hidden" >
< div id = "searchresults-header" class = "searchresults-header" > < / div >
< ul id = "searchresults" >
< / ul >
< / div >
< / div >
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
< script >
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
< / script >
< div id = "content" class = "content" >
< main >
< h1 id = "multi-repository-strategy-analysis" > < a class = "header" href = "#multi-repository-strategy-analysis" > Multi-Repository Strategy Analysis< / a > < / h1 >
< p > < strong > Date:< / strong > 2025-10-01
< strong > Status:< / strong > Strategic Analysis
< strong > Related:< / strong > < a href = "repo-dist-analysis.html" > Repository Distribution Analysis< / a > < / p >
< h2 id = "executive-summary" > < a class = "header" href = "#executive-summary" > Executive Summary< / a > < / h2 >
< p > This document analyzes a < strong > multi-repository strategy< / strong > as an alternative to the monorepo approach. After careful consideration of the provisioning system’ < strong > hybrid approach with 4 core repositories< / strong > is recommended, avoiding submodules in favor of a cleaner package-based dependency model.< / p >
< hr / >
< h2 id = "repository-architecture-options" > < a class = "header" href = "#repository-architecture-options" > Repository Architecture Options< / a > < / h2 >
< h3 id = "option-a-pure-monorepo-original-recommendation" > < a class = "header" href = "#option-a-pure-monorepo-original-recommendation" > Option A: Pure Monorepo (Original Recommendation)< / a > < / h3 >
< p > < strong > Single repository:< / strong > < code > provisioning< / code > < / p >
< p > < strong > Pros:< / strong > < / p >
< ul >
< li > Simplest development workflow< / li >
< li > Atomic cross-component changes< / li >
< li > Single version number< / li >
< li > One CI/CD pipeline< / li >
< / ul >
< p > < strong > Cons:< / strong > < / p >
< ul >
< li > Large repository size< / li >
< li > Mixed language tooling (Rust + Nushell)< / li >
< li > All-or-nothing updates< / li >
< li > Unclear ownership boundaries< / li >
< / ul >
< h3 id = "option-b-multi-repo-with-submodules--not-recommended" > < a class = "header" href = "#option-b-multi-repo-with-submodules--not-recommended" > Option B: Multi-Repo with Submodules (❌ Not Recommended)< / a > < / h3 >
< p > < strong > Repositories:< / strong > < / p >
< ul >
< li > < code > provisioning-core< / code > (main, contains submodules)< / li >
< li > < code > provisioning-platform< / code > (submodule)< / li >
< li > < code > provisioning-extensions< / code > (submodule)< / li >
< li > < code > provisioning-workspace< / code > (submodule)< / li >
< / ul >
< p > < strong > Why Not Recommended:< / strong > < / p >
< ul >
< li > Submodule hell: complex, error-prone workflows< / li >
< li > Detached HEAD issues< / li >
< li > Update synchronization nightmares< / li >
< li > Clone complexity for users< / li >
< li > Difficult to maintain version compatibility< / li >
< li > Poor developer experience< / li >
< / ul >
< h3 id = "option-c-multi-repo-with-package-dependencies--recommended" > < a class = "header" href = "#option-c-multi-repo-with-package-dependencies--recommended" > Option C: Multi-Repo with Package Dependencies (✅ RECOMMENDED)< / a > < / h3 >
< p > < strong > Independent repositories with package-based integration:< / strong > < / p >
< ul >
< li > < code > provisioning-core< / code > - Nushell libraries and KCL schemas< / li >
< li > < code > provisioning-platform< / code > - Rust services (orchestrator, control-center, MCP)< / li >
< li > < code > provisioning-extensions< / code > - Extension marketplace/catalog< / li >
< li > < code > provisioning-workspace< / code > - Project templates and examples< / li >
< li > < code > provisioning-distribution< / code > - Release automation and packaging< / li >
< / ul >
< p > < strong > Why Recommended:< / strong > < / p >
< ul >
< li > Clean separation of concerns< / li >
< li > Independent versioning and release cycles< / li >
< li > Language-specific tooling and workflows< / li >
< li > Clear ownership boundaries< / li >
< li > Package-based dependencies (no submodules)< / li >
< li > Easier community contributions< / li >
< / ul >
< hr / >
< h2 id = "recommended-multi-repo-architecture" > < a class = "header" href = "#recommended-multi-repo-architecture" > Recommended Multi-Repo Architecture< / a > < / h2 >
< h3 id = "repository-1-provisioning-core" > < a class = "header" href = "#repository-1-provisioning-core" > Repository 1: < code > provisioning-core< / code > < / a > < / h3 >
< p > < strong > Purpose:< / strong > Core Nushell infrastructure automation engine< / p >
< p > < strong > Contents:< / strong > < / p >
2026-01-08 09:55:37 +00:00
< pre > < code class = "language-plaintext" > provisioning-core/
2025-12-11 21:50:42 +00:00
├── nulib/ # Nushell libraries
│ ├── lib_provisioning/ # Core library functions
│ ├── servers/ # Server management
│ ├── taskservs/ # Task service management
│ ├── clusters/ # Cluster management
│ └── workflows/ # Workflow orchestration
├── cli/ # CLI entry point
│ └── provisioning # Pure Nushell CLI
├── kcl/ # KCL schemas
│ ├── main.k
│ ├── settings.k
│ ├── server.k
│ ├── cluster.k
│ └── workflows.k
├── config/ # Default configurations
│ └── config.defaults.toml
├── templates/ # Core templates
├── tools/ # Build and packaging tools
├── tests/ # Core tests
├── docs/ # Core documentation
├── LICENSE
├── README.md
├── CHANGELOG.md
└── version.toml # Core version file
2026-01-08 09:55:37 +00:00
```plaintext
**Technology:** Nushell, KCL
**Primary Language:** Nushell
**Release Frequency:** Monthly (stable)
**Ownership:** Core team
**Dependencies:** None (foundation)
**Package Output:**
- `provisioning-core-{version}.tar.gz` - Installable package
- Published to package registry
**Installation Path:**
```plaintext
/usr/local/
2025-12-11 21:50:42 +00:00
├── bin/provisioning
├── lib/provisioning/
└── share/provisioning/
2026-01-08 09:55:37 +00:00
```plaintext
---
### Repository 2: `provisioning-platform`
**Purpose:** High-performance Rust platform services
**Contents:**
```plaintext
provisioning-platform/
2025-12-11 21:50:42 +00:00
├── orchestrator/ # Rust orchestrator
│ ├── src/
│ ├── tests/
│ ├── benches/
│ └── Cargo.toml
├── control-center/ # Web control center (Leptos)
│ ├── src/
│ ├── tests/
│ └── Cargo.toml
├── mcp-server/ # Model Context Protocol server
│ ├── src/
│ ├── tests/
│ └── Cargo.toml
├── api-gateway/ # REST API gateway
│ ├── src/
│ ├── tests/
│ └── Cargo.toml
├── shared/ # Shared Rust libraries
│ ├── types/
│ └── utils/
├── docs/ # Platform documentation
├── Cargo.toml # Workspace root
├── Cargo.lock
├── LICENSE
├── README.md
└── CHANGELOG.md
2026-01-08 09:55:37 +00:00
```plaintext
**Technology:** Rust, WebAssembly
**Primary Language:** Rust
**Release Frequency:** Bi-weekly (fast iteration)
**Ownership:** Platform team
**Dependencies:**
- `provisioning-core` (runtime integration, loose coupling)
**Package Output:**
- `provisioning-platform-{version}.tar.gz` - Binaries
- Binaries for: Linux (x86_64, arm64), macOS (x86_64, arm64)
**Installation Path:**
```plaintext
/usr/local/
2025-12-11 21:50:42 +00:00
├── bin/
│ ├── provisioning-orchestrator
│ └── provisioning-control-center
└── share/provisioning/platform/
2026-01-08 09:55:37 +00:00
```plaintext
**Integration with Core:**
- Platform services call `provisioning` CLI via subprocess
- No direct code dependencies
- Communication via REST API and file-based queues
- Core and Platform can be deployed independently
---
### Repository 3: `provisioning-extensions`
**Purpose:** Extension marketplace and community modules
**Contents:**
```plaintext
provisioning-extensions/
2025-12-11 21:50:42 +00:00
├── registry/ # Extension registry
│ ├── index.json # Searchable index
│ └── catalog/ # Extension metadata
├── providers/ # Additional cloud providers
│ ├── azure/
│ ├── gcp/
│ ├── digitalocean/
│ └── hetzner/
├── taskservs/ # Community task services
│ ├── databases/
│ │ ├── mongodb/
│ │ ├── redis/
│ │ └── cassandra/
│ ├── development/
│ │ ├── gitlab/
│ │ ├── jenkins/
│ │ └── sonarqube/
│ └── observability/
│ ├── prometheus/
│ ├── grafana/
│ └── loki/
├── clusters/ # Cluster templates
│ ├── ml-platform/
│ ├── data-pipeline/
│ └── gaming-backend/
├── workflows/ # Workflow templates
├── tools/ # Extension development tools
├── docs/ # Extension development guide
├── LICENSE
└── README.md
2026-01-08 09:55:37 +00:00
```plaintext
**Technology:** Nushell, KCL
**Primary Language:** Nushell
**Release Frequency:** Continuous (per-extension)
**Ownership:** Community + Core team
**Dependencies:**
- `provisioning-core` (extends core functionality)
**Package Output:**
- Individual extension packages: `provisioning-ext-{name}-{version}.tar.gz`
- Registry index for discovery
**Installation:**
```bash
# Install extension via core CLI
2025-12-11 21:50:42 +00:00
provisioning extension install mongodb
provisioning extension install azure-provider
2026-01-08 09:55:37 +00:00
```plaintext
**Extension Structure:**
Each extension is self-contained:
```plaintext
mongodb/
2025-12-11 21:50:42 +00:00
├── manifest.toml # Extension metadata
├── taskserv.nu # Implementation
├── templates/ # Templates
├── kcl/ # KCL schemas
├── tests/ # Tests
└── README.md
2026-01-08 09:55:37 +00:00
```plaintext
---
### Repository 4: `provisioning-workspace`
**Purpose:** Project templates and starter kits
**Contents:**
```plaintext
provisioning-workspace/
2025-12-11 21:50:42 +00:00
├── templates/ # Workspace templates
│ ├── minimal/ # Minimal starter
│ ├── kubernetes/ # Full K8s cluster
│ ├── multi-cloud/ # Multi-cloud setup
│ ├── microservices/ # Microservices platform
│ ├── data-platform/ # Data engineering
│ └── ml-ops/ # MLOps platform
├── examples/ # Complete examples
│ ├── blog-deployment/
│ ├── e-commerce/
│ └── saas-platform/
├── blueprints/ # Architecture blueprints
├── docs/ # Template documentation
├── tools/ # Template scaffolding
│ └── create-workspace.nu
├── LICENSE
└── README.md
2026-01-08 09:55:37 +00:00
```plaintext
**Technology:** Configuration files, KCL
**Primary Language:** TOML, KCL, YAML
**Release Frequency:** Quarterly (stable templates)
**Ownership:** Community + Documentation team
**Dependencies:**
- `provisioning-core` (templates use core)
- `provisioning-extensions` (may reference extensions)
**Package Output:**
- `provisioning-templates-{version}.tar.gz`
**Usage:**
```bash
# Create workspace from template
2025-12-11 21:50:42 +00:00
provisioning workspace init my-project --template kubernetes
# Or use separate tool
gh repo create my-project --template provisioning-workspace
cd my-project
provisioning workspace init
2026-01-08 09:55:37 +00:00
```plaintext
---
### Repository 5: `provisioning-distribution`
**Purpose:** Release automation, packaging, and distribution infrastructure
**Contents:**
```plaintext
provisioning-distribution/
2025-12-11 21:50:42 +00:00
├── release-automation/ # Automated release workflows
│ ├── build-all.nu # Build all packages
│ ├── publish.nu # Publish to registries
│ └── validate.nu # Validation suite
├── installers/ # Installation scripts
│ ├── install.nu # Nushell installer
│ ├── install.sh # Bash installer
│ └── install.ps1 # PowerShell installer
├── packaging/ # Package builders
│ ├── core/
│ ├── platform/
│ └── extensions/
├── registry/ # Package registry backend
│ ├── api/ # Registry REST API
│ └── storage/ # Package storage
├── ci-cd/ # CI/CD configurations
│ ├── github/ # GitHub Actions
│ ├── gitlab/ # GitLab CI
│ └── jenkins/ # Jenkins pipelines
├── version-management/ # Cross-repo version coordination
│ ├── versions.toml # Version matrix
│ └── compatibility.toml # Compatibility matrix
├── docs/ # Distribution documentation
│ ├── release-process.md
│ └── packaging-guide.md
├── LICENSE
└── README.md
2026-01-08 09:55:37 +00:00
```plaintext
**Technology:** Nushell, Bash, CI/CD
**Primary Language:** Nushell, YAML
**Release Frequency:** As needed
**Ownership:** Release engineering team
**Dependencies:** All repositories (orchestrates releases)
**Responsibilities:**
- Build packages from all repositories
- Coordinate multi-repo releases
- Publish to package registries
- Manage version compatibility
- Generate release notes
- Host package registry
---
## Dependency and Integration Model
### Package-Based Dependencies (Not Submodules)
```plaintext
┌─────────────────────────────────────────────────────────────┐
2025-12-11 21:50:42 +00:00
│ provisioning-distribution │
│ (Release orchestration & registry) │
└──────────────────────────┬──────────────────────────────────┘
│ publishes packages
↓
┌──────────────┐
│ Registry │
└──────┬───────┘
│
┌──────────────────┼──────────────────┐
↓ ↓ ↓
┌───────────────┐ ┌──────────────┐ ┌──────────────┐
│ provisioning │ │ provisioning │ │ provisioning │
│ -core │ │ -platform │ │ -extensions │
└───────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
│ │ depends on │ extends
│ └─────────┐ │
│ ↓ │
└───────────────────────────────────→┘
runtime integration
2026-01-08 09:55:37 +00:00
```plaintext
### Integration Mechanisms
#### 1. **Core ↔ Platform Integration**
**Method:** Loose coupling via CLI + REST API
```nushell
# Platform calls Core CLI (subprocess)
2025-12-11 21:50:42 +00:00
def create-server [name: string] {
# Orchestrator executes Core CLI
^provisioning server create $name --infra production
}
# Core calls Platform API (HTTP)
def submit-workflow [workflow: record] {
http post http://localhost:9090/workflows/submit $workflow
}
2026-01-08 09:55:37 +00:00
```plaintext
**Version Compatibility:**
```toml
# platform/Cargo.toml
2025-12-11 21:50:42 +00:00
[package.metadata.provisioning]
core-version = "^3.0" # Compatible with core 3.x
2026-01-08 09:55:37 +00:00
```plaintext
#### 2. **Core ↔ Extensions Integration**
**Method:** Plugin/module system
```nushell
# Extension manifest
2025-12-11 21:50:42 +00:00
# extensions/mongodb/manifest.toml
[extension]
name = "mongodb"
version = "1.0.0"
type = "taskserv"
core-version = "^3.0"
[dependencies]
provisioning-core = "^3.0"
# Extension installation
# Core downloads and validates extension
provisioning extension install mongodb
# → Downloads from registry
# → Validates compatibility
# → Installs to ~/.provisioning/extensions/mongodb
2026-01-08 09:55:37 +00:00
```plaintext
#### 3. **Workspace Templates**
**Method:** Git templates or package templates
```bash
# Option 1: GitHub template repository
2025-12-11 21:50:42 +00:00
gh repo create my-infra --template provisioning-workspace
cd my-infra
provisioning workspace init
# Option 2: Template package
provisioning workspace create my-infra --template kubernetes
# → Downloads template package
# → Scaffolds workspace
# → Initializes configuration
2026-01-08 09:55:37 +00:00
```plaintext
---
## Version Management Strategy
### Semantic Versioning Per Repository
Each repository maintains independent semantic versioning:
```plaintext
provisioning-core: 3.2.1
2025-12-11 21:50:42 +00:00
provisioning-platform: 2.5.3
provisioning-extensions: (per-extension versioning)
provisioning-workspace: 1.4.0
2026-01-08 09:55:37 +00:00
```plaintext
### Compatibility Matrix
**`provisioning-distribution/version-management/versions.toml`:**
```toml
# Version compatibility matrix
2025-12-11 21:50:42 +00:00
[compatibility]
# Core versions and compatible platform versions
[compatibility.core]
"3.2.1" = { platform = "^2.5", extensions = "^1.0", workspace = "^1.0" }
"3.2.0" = { platform = "^2.4", extensions = "^1.0", workspace = "^1.0" }
"3.1.0" = { platform = "^2.3", extensions = "^0.9", workspace = "^1.0" }
# Platform versions and compatible core versions
[compatibility.platform]
"2.5.3" = { core = "^3.2", min-core = "3.2.0" }
"2.5.0" = { core = "^3.1", min-core = "3.1.0" }
# Release bundles (tested combinations)
[bundles]
[bundles.stable-3.2]
name = "Stable 3.2 Bundle"
release-date = "2025-10-15"
core = "3.2.1"
platform = "2.5.3"
extensions = ["mongodb@1.2.0", "redis@1.1.0", "azure@2.0.0"]
workspace = "1.4.0"
[bundles.lts-3.1]
name = "LTS 3.1 Bundle"
release-date = "2025-09-01"
lts-until = "2026-09-01"
core = "3.1.5"
platform = "2.4.8"
workspace = "1.3.0"
2026-01-08 09:55:37 +00:00
```plaintext
### Release Coordination
**Coordinated releases** for major versions:
```bash
# Major release: All repos release together
2025-12-11 21:50:42 +00:00
provisioning-core: 3.0.0
provisioning-platform: 2.0.0
provisioning-workspace: 1.0.0
# Minor/patch releases: Independent
provisioning-core: 3.1.0 (adds features, platform stays 2.0.x)
provisioning-platform: 2.1.0 (improves orchestrator, core stays 3.1.x)
2026-01-08 09:55:37 +00:00
```plaintext
---
## Development Workflow
### Working on Single Repository
```bash
# Developer working on core only
2025-12-11 21:50:42 +00:00
git clone https://github.com/yourorg/provisioning-core
cd provisioning-core
# Install dependencies
just install-deps
# Development
just dev-check
just test
# Build package
just build
# Test installation locally
just install-dev
2026-01-08 09:55:37 +00:00
```plaintext
### Working Across Repositories
```bash
# Scenario: Adding new feature requiring core + platform changes
2025-12-11 21:50:42 +00:00
# 1. Clone both repositories
git clone https://github.com/yourorg/provisioning-core
git clone https://github.com/yourorg/provisioning-platform
# 2. Create feature branches
cd provisioning-core
git checkout -b feat/batch-workflow-v2
cd ../provisioning-platform
git checkout -b feat/batch-workflow-v2
# 3. Develop with local linking
cd provisioning-core
just install-dev # Installs to /usr/local/bin/provisioning
cd ../provisioning-platform
# Platform uses system provisioning CLI (local dev version)
cargo run
# 4. Test integration
cd ../provisioning-core
just test-integration
cd ../provisioning-platform
cargo test
# 5. Create PRs in both repositories
# PR #123 in provisioning-core
# PR #456 in provisioning-platform (references core PR)
# 6. Coordinate merge
# Merge core PR first, cut release 3.3.0
# Update platform dependency to core 3.3.0
# Merge platform PR, cut release 2.6.0
2026-01-08 09:55:37 +00:00
```plaintext
### Testing Cross-Repo Integration
```bash
# Integration tests in provisioning-distribution
2025-12-11 21:50:42 +00:00
cd provisioning-distribution
# Test specific version combination
just test-integration \
--core 3.3.0 \
--platform 2.6.0
# Test bundle
just test-bundle stable-3.3
2026-01-08 09:55:37 +00:00
```plaintext
---
## Distribution Strategy
### Individual Repository Releases
Each repository releases independently:
```bash
# Core release
2025-12-11 21:50:42 +00:00
cd provisioning-core
git tag v3.2.1
git push --tags
# → GitHub Actions builds package
# → Publishes to package registry
# Platform release
cd provisioning-platform
git tag v2.5.3
git push --tags
# → GitHub Actions builds binaries
# → Publishes to package registry
2026-01-08 09:55:37 +00:00
```plaintext
### Bundle Releases (Coordinated)
Distribution repository creates tested bundles:
```bash
cd provisioning-distribution
2025-12-11 21:50:42 +00:00
# Create bundle
just create-bundle stable-3.2 \
--core 3.2.1 \
--platform 2.5.3 \
--workspace 1.4.0
# Test bundle
just test-bundle stable-3.2
# Publish bundle
just publish-bundle stable-3.2
# → Creates meta-package with all components
# → Publishes bundle to registry
# → Updates documentation
2026-01-08 09:55:37 +00:00
```plaintext
### User Installation Options
#### Option 1: Bundle Installation (Recommended for Users)
```bash
# Install stable bundle (easiest)
2025-12-11 21:50:42 +00:00
curl -fsSL https://get.provisioning.io | sh
# Installs:
# - provisioning-core 3.2.1
# - provisioning-platform 2.5.3
# - provisioning-workspace 1.4.0
2026-01-08 09:55:37 +00:00
```plaintext
#### Option 2: Individual Component Installation
```bash
# Install only core (minimal)
2025-12-11 21:50:42 +00:00
curl -fsSL https://get.provisioning.io/core | sh
# Add platform later
provisioning install platform
# Add extensions
provisioning extension install mongodb
2026-01-08 09:55:37 +00:00
```plaintext
#### Option 3: Custom Combination
```bash
# Install specific versions
2025-12-11 21:50:42 +00:00
provisioning install core@3.1.0
provisioning install platform@2.4.0
2026-01-08 09:55:37 +00:00
```plaintext
---
## Repository Ownership and Contribution Model
### Core Team Ownership
| Repository | Primary Owner | Contribution Model |
|------------|---------------|-------------------|
| `provisioning-core` | Core Team | Strict review, stable API |
| `provisioning-platform` | Platform Team | Fast iteration, performance focus |
| `provisioning-extensions` | Community + Core | Open contributions, moderated |
| `provisioning-workspace` | Docs Team | Template contributions welcome |
| `provisioning-distribution` | Release Engineering | Core team only |
### Contribution Workflow
**For Core:**
1. Create issue in `provisioning-core`
2. Discuss design
3. Submit PR with tests
4. Strict code review
5. Merge to `main`
6. Release when ready
**For Extensions:**
1. Create extension in `provisioning-extensions`
2. Follow extension guidelines
3. Submit PR
4. Community review
5. Merge and publish to registry
6. Independent versioning
**For Platform:**
1. Create issue in `provisioning-platform`
2. Implement with benchmarks
3. Submit PR
4. Performance review
5. Merge and release
---
## CI/CD Strategy
### Per-Repository CI/CD
**Core CI (`provisioning-core/.github/workflows/ci.yml`):**
```yaml
name: Core CI
2025-12-11 21:50:42 +00:00
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install Nushell
run: cargo install nu
- name: Run tests
run: just test
- name: Validate KCL schemas
run: just validate-kcl
package:
runs-on: ubuntu-latest
if: startsWith(github.ref, 'refs/tags/v')
steps:
- uses: actions/checkout@v3
- name: Build package
run: just build
- name: Publish to registry
run: just publish
env:
REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
2026-01-08 09:55:37 +00:00
```plaintext
**Platform CI (`provisioning-platform/.github/workflows/ci.yml`):**
```yaml
name: Platform CI
2025-12-11 21:50:42 +00:00
on: [push, pull_request]
jobs:
test:
strategy:
matrix:
os: [ubuntu-latest, macos-latest]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v3
- name: Build
run: cargo build --release
- name: Test
run: cargo test --workspace
- name: Benchmark
run: cargo bench
cross-compile:
runs-on: ubuntu-latest
if: startsWith(github.ref, 'refs/tags/v')
steps:
- uses: actions/checkout@v3
- name: Build for Linux x86_64
run: cargo build --release --target x86_64-unknown-linux-gnu
- name: Build for Linux arm64
run: cargo build --release --target aarch64-unknown-linux-gnu
- name: Publish binaries
run: just publish-binaries
2026-01-08 09:55:37 +00:00
```plaintext
### Integration Testing (Distribution Repo)
**Distribution CI (`provisioning-distribution/.github/workflows/integration.yml`):**
```yaml
name: Integration Tests
2025-12-11 21:50:42 +00:00
on:
schedule:
- cron: '0 0 * * *' # Daily
workflow_dispatch:
jobs:
test-bundle:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install bundle
run: |
nu release-automation/install-bundle.nu stable-3.2
- name: Run integration tests
run: |
nu tests/integration/test-all.nu
- name: Test upgrade path
run: |
nu tests/integration/test-upgrade.nu 3.1.0 3.2.1
2026-01-08 09:55:37 +00:00
```plaintext
---
## File and Directory Structure Comparison
### Monorepo Structure
```plaintext
provisioning/ (One repo, ~500MB)
2025-12-11 21:50:42 +00:00
├── core/ (Nushell)
├── platform/ (Rust)
├── extensions/ (Community)
├── workspace/ (Templates)
└── distribution/ (Build)
2026-01-08 09:55:37 +00:00
```plaintext
### Multi-Repo Structure
```plaintext
provisioning-core/ (Repo 1, ~50MB)
2025-12-11 21:50:42 +00:00
├── nulib/
├── cli/
├── kcl/
└── tools/
provisioning-platform/ (Repo 2, ~150MB with target/)
├── orchestrator/
├── control-center/
├── mcp-server/
└── Cargo.toml
provisioning-extensions/ (Repo 3, ~100MB)
├── registry/
├── providers/
├── taskservs/
└── clusters/
provisioning-workspace/ (Repo 4, ~20MB)
├── templates/
├── examples/
└── blueprints/
provisioning-distribution/ (Repo 5, ~30MB)
├── release-automation/
├── installers/
├── packaging/
└── registry/
2026-01-08 09:55:37 +00:00
```plaintext
---
## Decision Matrix
| Criterion | Monorepo | Multi-Repo |
|-----------|----------|------------|
| **Development Complexity** | Simple | Moderate |
| **Clone Size** | Large (~500MB) | Small (50-150MB each) |
| **Cross-Component Changes** | Easy (atomic) | Moderate (coordinated) |
| **Independent Releases** | Difficult | Easy |
| **Language-Specific Tooling** | Mixed | Clean |
| **Community Contributions** | Harder (big repo) | Easier (focused repos) |
| **Version Management** | Simple (one version) | Complex (matrix) |
| **CI/CD Complexity** | Simple (one pipeline) | Moderate (multiple) |
| **Ownership Clarity** | Unclear | Clear |
| **Extension Ecosystem** | Monolithic | Modular |
| **Build Time** | Long (build all) | Short (build one) |
| **Testing Isolation** | Difficult | Easy |
---
## Recommended Approach: Multi-Repo
### Why Multi-Repo Wins for This Project
1. **Clear Separation of Concerns**
- Nushell core vs Rust platform are different domains
- Different teams can own different repos
- Different release cadences make sense
2. **Language-Specific Tooling**
- `provisioning-core`: Nushell-focused, simple testing
- `provisioning-platform`: Rust workspace, Cargo tooling
- No mixed tooling confusion
3. **Community Contributions**
- Extensions repo is easier to contribute to
- Don't need to clone entire monorepo
- Clearer contribution guidelines per repo
4. **Independent Versioning**
- Core can stay stable (3.x for months)
- Platform can iterate fast (2.x weekly)
- Extensions have own lifecycles
5. **Build Performance**
- Only build what changed
- Faster CI/CD per repo
- Parallel builds across repos
6. **Extension Ecosystem**
- Extensions repo becomes marketplace
- Third-party extensions can live separately
- Registry becomes discovery mechanism
### Implementation Strategy
**Phase 1: Split Repositories (Week 1-2)**
1. Create 5 new repositories
2. Extract code from monorepo
3. Set up CI/CD for each
4. Create initial packages
**Phase 2: Package Integration (Week 3)**
1. Implement package registry
2. Create installers
3. Set up version compatibility matrix
4. Test cross-repo integration
**Phase 3: Distribution System (Week 4)**
1. Implement bundle system
2. Create release automation
3. Set up package hosting
4. Document release process
**Phase 4: Migration (Week 5)**
1. Migrate existing users
2. Update documentation
3. Archive monorepo
4. Announce new structure
---
## Conclusion
**Recommendation: Multi-Repository Architecture with Package-Based Integration**
The multi-repo approach provides:
- ✅ Clear separation between Nushell core and Rust platform
- ✅ Independent release cycles for different components
- ✅ Better community contribution experience
- ✅ Language-specific tooling and workflows
- ✅ Modular extension ecosystem
- ✅ Faster builds and CI/CD
- ✅ Clear ownership boundaries
**Avoid:** Submodules (complexity nightmare)
**Use:** Package-based dependencies with version compatibility matrix
This architecture scales better for your project's growth, supports a community extension ecosystem, and provides professional-grade separation of concerns while maintaining integration through a well-designed package system.
---
## Next Steps
1. **Approve multi-repo strategy**
2. **Create repository split plan**
3. **Set up GitHub organizations/teams**
4. **Implement package registry**
5. **Begin repository extraction**
Would you like me to create a detailed **repository split implementation plan** next?
2025-12-11 21:50:42 +00:00
< / code > < / pre >
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
2026-01-08 09:55:37 +00:00
< a rel = "prev" href = "../architecture/multi-repo-architecture.html" class = "mobile-nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
2025-12-11 21:50:42 +00:00
< i class = "fa fa-angle-left" > < / i >
< / a >
2026-01-08 09:55:37 +00:00
< a rel = "next prefetch" href = "../architecture/database-and-config-architecture.html" class = "mobile-nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
2025-12-11 21:50:42 +00:00
< i class = "fa fa-angle-right" > < / i >
< / a >
< div style = "clear: both" > < / div >
< / nav >
< / div >
< / div >
< nav class = "nav-wide-wrapper" aria-label = "Page navigation" >
2026-01-08 09:55:37 +00:00
< a rel = "prev" href = "../architecture/multi-repo-architecture.html" class = "nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
2025-12-11 21:50:42 +00:00
< i class = "fa fa-angle-left" > < / i >
< / a >
2026-01-08 09:55:37 +00:00
< a rel = "next prefetch" href = "../architecture/database-and-config-architecture.html" class = "nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
2025-12-11 21:50:42 +00:00
< i class = "fa fa-angle-right" > < / i >
< / a >
< / nav >
< / div >
< script >
window.playground_copyable = true;
< / script >
< script src = "../elasticlunr.min.js" > < / script >
< script src = "../mark.min.js" > < / script >
< script src = "../searcher.js" > < / script >
< script src = "../clipboard.min.js" > < / script >
< script src = "../highlight.js" > < / script >
< script src = "../book.js" > < / script >
<!-- Custom JS scripts -->
< / div >
< / body >
< / html >
