44648e3206
- Remove KCL ecosystem (~220 files deleted) - Migrate all infrastructure to Nickel schema system - Consolidate documentation: legacy docs → provisioning/docs/src/ - Add CI/CD workflows (.github/) and Rust build config (.cargo/) - Update core system for Nickel schema parsing - Update README.md and CHANGES.md for v5.0.0 release - Fix pre-commit hooks: end-of-file, trailing-whitespace - Breaking changes: KCL workspaces require migration - Migration bridge available in docs/src/development/
1234 lines
40 KiB
HTML
1234 lines
40 KiB
HTML
<!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’s architecture, a <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>
|
||
<pre><code class="language-plaintext">provisioning-core/
|
||
├── 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
|
||
```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/
|
||
├── bin/provisioning
|
||
├── lib/provisioning/
|
||
└── share/provisioning/
|
||
```plaintext
|
||
|
||
---
|
||
|
||
### Repository 2: `provisioning-platform`
|
||
|
||
**Purpose:** High-performance Rust platform services
|
||
|
||
**Contents:**
|
||
|
||
```plaintext
|
||
provisioning-platform/
|
||
├── 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
|
||
```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/
|
||
├── bin/
|
||
│ ├── provisioning-orchestrator
|
||
│ └── provisioning-control-center
|
||
└── share/provisioning/platform/
|
||
```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/
|
||
├── 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
|
||
```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
|
||
provisioning extension install mongodb
|
||
provisioning extension install azure-provider
|
||
```plaintext
|
||
|
||
**Extension Structure:**
|
||
Each extension is self-contained:
|
||
|
||
```plaintext
|
||
mongodb/
|
||
├── manifest.toml # Extension metadata
|
||
├── taskserv.nu # Implementation
|
||
├── templates/ # Templates
|
||
├── kcl/ # KCL schemas
|
||
├── tests/ # Tests
|
||
└── README.md
|
||
```plaintext
|
||
|
||
---
|
||
|
||
### Repository 4: `provisioning-workspace`
|
||
|
||
**Purpose:** Project templates and starter kits
|
||
|
||
**Contents:**
|
||
|
||
```plaintext
|
||
provisioning-workspace/
|
||
├── 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
|
||
```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
|
||
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
|
||
```plaintext
|
||
|
||
---
|
||
|
||
### Repository 5: `provisioning-distribution`
|
||
|
||
**Purpose:** Release automation, packaging, and distribution infrastructure
|
||
|
||
**Contents:**
|
||
|
||
```plaintext
|
||
provisioning-distribution/
|
||
├── 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
|
||
```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
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ provisioning-distribution │
|
||
│ (Release orchestration & registry) │
|
||
└──────────────────────────┬──────────────────────────────────┘
|
||
│ publishes packages
|
||
↓
|
||
┌──────────────┐
|
||
│ Registry │
|
||
└──────┬───────┘
|
||
│
|
||
┌──────────────────┼──────────────────┐
|
||
↓ ↓ ↓
|
||
┌───────────────┐ ┌──────────────┐ ┌──────────────┐
|
||
│ provisioning │ │ provisioning │ │ provisioning │
|
||
│ -core │ │ -platform │ │ -extensions │
|
||
└───────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
||
│ │ │
|
||
│ │ depends on │ extends
|
||
│ └─────────┐ │
|
||
│ ↓ │
|
||
└───────────────────────────────────→┘
|
||
runtime integration
|
||
```plaintext
|
||
|
||
### Integration Mechanisms
|
||
|
||
#### 1. **Core ↔ Platform Integration**
|
||
|
||
**Method:** Loose coupling via CLI + REST API
|
||
|
||
```nushell
|
||
# Platform calls Core CLI (subprocess)
|
||
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
|
||
}
|
||
```plaintext
|
||
|
||
**Version Compatibility:**
|
||
|
||
```toml
|
||
# platform/Cargo.toml
|
||
[package.metadata.provisioning]
|
||
core-version = "^3.0" # Compatible with core 3.x
|
||
```plaintext
|
||
|
||
#### 2. **Core ↔ Extensions Integration**
|
||
|
||
**Method:** Plugin/module system
|
||
|
||
```nushell
|
||
# Extension manifest
|
||
# 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
|
||
```plaintext
|
||
|
||
#### 3. **Workspace Templates**
|
||
|
||
**Method:** Git templates or package templates
|
||
|
||
```bash
|
||
# Option 1: GitHub template repository
|
||
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
|
||
```plaintext
|
||
|
||
---
|
||
|
||
## Version Management Strategy
|
||
|
||
### Semantic Versioning Per Repository
|
||
|
||
Each repository maintains independent semantic versioning:
|
||
|
||
```plaintext
|
||
provisioning-core: 3.2.1
|
||
provisioning-platform: 2.5.3
|
||
provisioning-extensions: (per-extension versioning)
|
||
provisioning-workspace: 1.4.0
|
||
```plaintext
|
||
|
||
### Compatibility Matrix
|
||
|
||
**`provisioning-distribution/version-management/versions.toml`:**
|
||
|
||
```toml
|
||
# Version compatibility matrix
|
||
[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"
|
||
```plaintext
|
||
|
||
### Release Coordination
|
||
|
||
**Coordinated releases** for major versions:
|
||
|
||
```bash
|
||
# Major release: All repos release together
|
||
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)
|
||
```plaintext
|
||
|
||
---
|
||
|
||
## Development Workflow
|
||
|
||
### Working on Single Repository
|
||
|
||
```bash
|
||
# Developer working on core only
|
||
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
|
||
```plaintext
|
||
|
||
### Working Across Repositories
|
||
|
||
```bash
|
||
# Scenario: Adding new feature requiring core + platform changes
|
||
|
||
# 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
|
||
```plaintext
|
||
|
||
### Testing Cross-Repo Integration
|
||
|
||
```bash
|
||
# Integration tests in provisioning-distribution
|
||
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
|
||
```plaintext
|
||
|
||
---
|
||
|
||
## Distribution Strategy
|
||
|
||
### Individual Repository Releases
|
||
|
||
Each repository releases independently:
|
||
|
||
```bash
|
||
# Core release
|
||
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
|
||
```plaintext
|
||
|
||
### Bundle Releases (Coordinated)
|
||
|
||
Distribution repository creates tested bundles:
|
||
|
||
```bash
|
||
cd provisioning-distribution
|
||
|
||
# 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
|
||
```plaintext
|
||
|
||
### User Installation Options
|
||
|
||
#### Option 1: Bundle Installation (Recommended for Users)
|
||
|
||
```bash
|
||
# Install stable bundle (easiest)
|
||
curl -fsSL https://get.provisioning.io | sh
|
||
|
||
# Installs:
|
||
# - provisioning-core 3.2.1
|
||
# - provisioning-platform 2.5.3
|
||
# - provisioning-workspace 1.4.0
|
||
```plaintext
|
||
|
||
#### Option 2: Individual Component Installation
|
||
|
||
```bash
|
||
# Install only core (minimal)
|
||
curl -fsSL https://get.provisioning.io/core | sh
|
||
|
||
# Add platform later
|
||
provisioning install platform
|
||
|
||
# Add extensions
|
||
provisioning extension install mongodb
|
||
```plaintext
|
||
|
||
#### Option 3: Custom Combination
|
||
|
||
```bash
|
||
# Install specific versions
|
||
provisioning install core@3.1.0
|
||
provisioning install platform@2.4.0
|
||
```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
|
||
|
||
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 }}
|
||
```plaintext
|
||
|
||
**Platform CI (`provisioning-platform/.github/workflows/ci.yml`):**
|
||
|
||
```yaml
|
||
name: Platform CI
|
||
|
||
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
|
||
```plaintext
|
||
|
||
### Integration Testing (Distribution Repo)
|
||
|
||
**Distribution CI (`provisioning-distribution/.github/workflows/integration.yml`):**
|
||
|
||
```yaml
|
||
name: Integration Tests
|
||
|
||
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
|
||
```plaintext
|
||
|
||
---
|
||
|
||
## File and Directory Structure Comparison
|
||
|
||
### Monorepo Structure
|
||
|
||
```plaintext
|
||
provisioning/ (One repo, ~500MB)
|
||
├── core/ (Nushell)
|
||
├── platform/ (Rust)
|
||
├── extensions/ (Community)
|
||
├── workspace/ (Templates)
|
||
└── distribution/ (Build)
|
||
```plaintext
|
||
|
||
### Multi-Repo Structure
|
||
|
||
```plaintext
|
||
provisioning-core/ (Repo 1, ~50MB)
|
||
├── 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/
|
||
```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?
|
||
</code></pre>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
<a rel="prev" href="../architecture/multi-repo-architecture.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
<i class="fa fa-angle-left"></i>
|
||
</a>
|
||
|
||
<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">
|
||
<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">
|
||
<a rel="prev" href="../architecture/multi-repo-architecture.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
<i class="fa fa-angle-left"></i>
|
||
</a>
|
||
|
||
<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">
|
||
<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>
|