# RuVector Release Pipeline Flow Diagram ``` ┌─────────────────────────────────────────────────────────────────┐ │ TRIGGER RELEASE PIPELINE │ │ │ │ Method 1: git tag v0.1.3 && git push origin v0.1.3 │ │ Method 2: Manual workflow_dispatch with version input │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ STAGE 1: VALIDATION │ │ ┌────────────────────────────────────────────────────────────┐ │ │ │ • cargo fmt --check │ │ │ │ • cargo clippy (all warnings as errors) │ │ │ │ • cargo test --workspace │ │ │ │ • npm run test:unit │ │ │ └────────────────────────────────────────────────────────────┘ │ │ Runner: ubuntu-22.04 │ │ Time: 3-12 minutes │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────┴─────────────────┐ │ │ ▼ ▼ ┌───────────────────────────┐ ┌───────────────────────────┐ │ STAGE 2: BUILD CRATES │ │ STAGE 3: BUILD WASM │ │ ┌─────────────────────┐ │ │ ┌─────────────────────┐ │ │ │ • Build 26 crates │ │ │ │ • ruvector-wasm │ │ │ │ • Dependency order │ │ │ │ • ruvector-gnn-wasm │ │ │ │ • Release mode │ │ │ │ • ruvector-graph- │ │ │ │ • Run tests │ │ │ │ wasm │ │ │ └─────────────────────┘ │ │ │ • tiny-dancer-wasm │ │ │ ubuntu-22.04 │ │ └─────────────────────┘ │ │ 5-20 minutes │ │ ubuntu-22.04 │ └───────────────────────────┘ │ 4-15 minutes │ │ └───────────────────────────┘ │ │ └──────────┬────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────────┐ │ STAGE 4: BUILD NATIVE (Parallel Matrix) │ │ ┌──────────────────────────────────────────────────────────────┐│ │ │ Platform 1 Platform 2 Platform 3 ││ │ │ linux-x64-gnu linux-arm64-gnu darwin-x64 ││ │ │ ubuntu-22.04 ubuntu-22.04 macos-13 ││ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││ │ │ │ napi-rs │ │ napi-rs │ │ napi-rs │ ││ │ │ │ build │ │ + cross │ │ build │ ││ │ │ │ │ │ compile │ │ │ ││ │ │ └──────────┘ └──────────┘ └──────────┘ ││ │ │ ││ │ │ Platform 4 Platform 5 ││ │ │ darwin-arm64 win32-x64-msvc ││ │ │ macos-14 windows-2022 ││ │ │ ┌──────────┐ ┌──────────┐ ││ │ │ │ napi-rs │ │ napi-rs │ ││ │ │ │ build │ │ build │ ││ │ │ │ │ │ │ ││ │ │ └──────────┘ └──────────┘ ││ │ └──────────────────────────────────────────────────────────────┘│ │ Time: 3-12 minutes per platform (runs in parallel) │ └──────────────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────┴────────────────────┐ │ │ ▼ ▼ ┌────────────────────────┐ ┌────────────────────────┐ │ STAGE 5: PUBLISH │ │ STAGE 6: PUBLISH │ │ RUST CRATES │ │ npm PACKAGES │ │ │ │ │ │ Publishing Order: │ │ Publishing Order: │ │ 1. ruvector-core │ │ 1. Platform packages │ │ 2. ruvector-metrics │ │ (@ruvector/core-*) │ │ 3. ruvector-filter │ │ 2. @ruvector/wasm │ │ 4. ruvector-snapshot │ │ 3. @ruvector/cli │ │ 5. ruvector- │ │ 4. @ruvector/ │ │ collections │ │ extensions │ │ ... (26 total) │ │ 5. @ruvector/core │ │ │ │ │ │ Target: crates.io │ │ Target: npmjs.com │ │ Auth: CARGO_REGISTRY_ │ │ Auth: NPM_TOKEN │ │ TOKEN │ │ │ │ Time: 5-10 minutes │ │ Time: 2-5 minutes │ └────────────────────────┘ └────────────────────────┘ │ │ └────────────────────┬────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ STAGE 7: CREATE GITHUB RELEASE │ │ ┌────────────────────────────────────────────────────────────┐ │ │ │ 1. Download all artifacts (native + WASM) │ │ │ │ 2. Package as .tar.gz files: │ │ │ │ - ruvector-native-linux-x64-gnu.tar.gz │ │ │ │ - ruvector-native-linux-arm64-gnu.tar.gz │ │ │ │ - ruvector-native-darwin-x64.tar.gz │ │ │ │ - ruvector-native-darwin-arm64.tar.gz │ │ │ │ - ruvector-native-win32-x64-msvc.tar.gz │ │ │ │ - ruvector-wasm.tar.gz │ │ │ │ 3. Generate comprehensive release notes │ │ │ │ 4. Create GitHub release with artifacts │ │ │ └────────────────────────────────────────────────────────────┘ │ │ Time: 2-3 minutes │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ STAGE 8: RELEASE SUMMARY │ │ ┌────────────────────────────────────────────────────────────┐ │ │ │ Generate final summary with: │ │ │ │ • Status of all jobs (success/failure) │ │ │ │ • Links to published packages │ │ │ │ • Verification steps │ │ │ │ • Next steps for maintainers │ │ │ └────────────────────────────────────────────────────────────┘ │ │ Always runs (even on failure) │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ RELEASE COMPLETE! 🎉 │ │ │ │ Published to: │ │ ✅ crates.io: https://crates.io/crates/ruvector-core │ │ ✅ npmjs.com: https://www.npmjs.com/package/@ruvector/core │ │ ✅ GitHub: https://github.com/ruvnet/ruvector/releases │ │ │ │ Total Time: 15-30 minutes (with caching) │ └─────────────────────────────────────────────────────────────────┘ ``` ## Key Features ### 🚀 Parallel Execution - Stages 2, 3, and 4 run simultaneously - 5 native platform builds run in parallel - Total time: ~60% faster than sequential ### 💾 Smart Caching - Rust dependencies cached via `Swatinem/rust-cache` - npm dependencies cached via `actions/setup-node` - wasm-pack binary cached - Cache hit rate: 70-95% ### 🔒 Security - Secrets never exposed in logs - Environment protection for production - Optional reviewer approval gates - Conditional publishing (tag or manual only) ### 🛡️ Error Handling - Continue on already-published packages - Graceful failure handling - Rate limiting protection (10s between publishes) - Comprehensive error logging ### 📊 Monitoring - Job summaries at each stage - Final comprehensive summary - Artifact upload/download tracking - GitHub release with all binaries ## Workflow Dependencies ``` ┌──────────┐ │ validate │──┐ └──────────┘ │ ├──> build-crates ──┐ │ │ ├──> build-wasm ─────┤ │ ├──> publish-crates ──┐ └──> build-native ───┤ │ ├──> publish-npm ─────┤ │ │ └─────────────────────┴──> create-release │ └──> release-summary ``` ## Critical Paths ### Path 1: Rust Publishing ``` validate → build-crates → publish-crates → create-release ``` **Time**: 15-25 minutes ### Path 2: npm Publishing ``` validate → build-native → publish-npm → create-release → build-wasm ─┘ ``` **Time**: 12-20 minutes ### Path 3: Release Creation ``` All paths → create-release → release-summary ``` **Time**: 2-3 minutes ## Artifact Flow ``` ┌──────────────┐ │ build-native │──> bindings-linux-x64-gnu.artifact │ │──> bindings-linux-arm64-gnu.artifact │ │──> bindings-darwin-x64.artifact │ │──> bindings-darwin-arm64.artifact │ │──> bindings-win32-x64-msvc.artifact └──────────────┘ │ ├──> publish-npm (downloads & publishes) │ └──> create-release (downloads & packages) ┌──────────────┐ │ build-wasm │──> wasm-packages.artifact └──────────────┘ │ ├──> publish-npm (downloads & publishes) │ └──> create-release (downloads & packages) ``` ## Environment Variables | Variable | Scope | Purpose | |----------|-------|---------| | `CARGO_TERM_COLOR` | Global | Colored Cargo output | | `RUST_BACKTRACE` | Global | Detailed error traces | | `CARGO_REGISTRY_TOKEN` | publish-crates | crates.io auth | | `NODE_AUTH_TOKEN` | publish-npm | npmjs.com auth | | `GITHUB_TOKEN` | create-release | GitHub API auth | ## Job Conditions | Job | Runs When | |-----|-----------| | `validate` | Always (unless skip_tests=true) | | `build-crates` | After validation passes | | `build-wasm` | After validation passes | | `build-native` | After validation passes | | `publish-crates` | Tag push OR manual + not dry_run | | `publish-npm` | Tag push OR manual + not dry_run | | `create-release` | All builds succeed + tag OR manual | | `release-summary` | Always (even on failure) | ## Quick Start Commands ```bash # Test the workflow locally (dry run) gh workflow run release.yml \ -f version=0.1.3-test \ -f dry_run=true # Trigger production release git tag v0.1.3 git push origin v0.1.3 # Emergency release (skip tests) gh workflow run release.yml \ -f version=0.1.3 \ -f skip_tests=true # View workflow status gh run list --workflow=release.yml ``` ## Support Matrix | Component | Platforms | Total | |-----------|-----------|-------| | Native Binaries | linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64 | 5 | | WASM Packages | Universal (wasm32-unknown-unknown) | 4 | | Rust Crates | Platform-independent source | 26 | | npm Packages | 5 platform + 4 core | 9 | **Total Release Artifacts**: 44 packages across 3 registries