Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'
This commit is contained in:
ruv
284
vendor/ruvector/.github/workflows/RELEASE-FLOW.md
vendored
Normal file
284
vendor/ruvector/.github/workflows/RELEASE-FLOW.md
vendored
Normal file
@@ -0,0 +1,284 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user