wifi-densepose/vendor/ruvector/docs/publishing/PUBLISHING.md

Publishing Guide

Complete guide for publishing rUvector packages to npm.

Table of Contents

• Overview
• Prerequisites
• Publishing Process
• Version Management
• CI/CD Workflow
• Manual Publishing
• Troubleshooting
• Post-Publication

Overview

rUvector uses automated publishing via GitHub Actions. When you push a version tag, the CI/CD pipeline:

1. Builds native binaries for all 5 platforms
2. Publishes platform-specific packages
3. Publishes the main @ruvector/core package

Published Packages

The publishing workflow creates these npm packages:

Platform-specific packages (native binaries):

• ruvector-core-darwin-arm64 - macOS Apple Silicon (M1/M2/M3)
• ruvector-core-darwin-x64 - macOS Intel
• ruvector-core-linux-arm64-gnu - Linux ARM64
• ruvector-core-linux-x64-gnu - Linux x64
• ruvector-core-win32-x64-msvc - Windows x64

Main package:

• @ruvector/core - Main package with TypeScript types and platform detection

Prerequisites

1. NPM Authentication

Ensure you have npm publish permissions:

npm whoami
# Should show your npm username

2. GitHub Secrets

The repository must have the NPM_TOKEN secret configured:

1. Go to Settings → Secrets and variables → Actions
2. Add NPM_TOKEN with your npm authentication token
3. Generate token at: https://www.npmjs.com/settings/[username]/tokens

3. Git Configuration

# Verify git user
git config user.name
git config user.email

# Verify remote
git remote -v

4. Build System Check

All platforms must build successfully:

# View latest build status
gh run list --workflow "Build Native Modules" --limit 1

# Or check PR directly
gh pr checks <PR-NUMBER>

Publishing Process

Option 1: Automated Publishing (Recommended)

This is the standard workflow for releases:

Step 1: Ensure All Builds Pass

# Check current build status
gh run list --limit 1

All 5 platform builds should be passing:

• ✅ darwin-arm64 (Apple Silicon)
• ✅ darwin-x64 (Intel Mac)
• ✅ linux-arm64-gnu
• ✅ linux-x64-gnu
• ✅ win32-x64-msvc

Step 2: Update Version

# Navigate to package directory
cd npm/core

# Bump version (choose one)
npm version patch   # 0.1.1 -> 0.1.2
npm version minor   # 0.1.1 -> 0.2.0
npm version major   # 0.1.1 -> 1.0.0

# Or manually edit package.json

Also update platform package versions to match:

# Edit npm/core/package.json
# Update optionalDependencies versions to match

Step 3: Commit Version Bump

cd /workspaces/ruvector

git add npm/core/package.json npm/package-lock.json
git commit -m "chore: bump version to X.Y.Z"
git push

Step 4: Create and Push Tag

# Create annotated tag
git tag vX.Y.Z -a -m "Release vX.Y.Z

- Feature 1
- Feature 2
- Bug fix 3"

# Push tag to trigger publishing
git push origin vX.Y.Z

Step 5: Monitor Publishing Workflow

# Watch workflow progress
gh run watch

# Or view in browser
gh run list --limit 1

The workflow will:

1. ⏳ Build all 5 platforms (~7 minutes)
2. ⏳ Upload artifacts
3. ⏳ Run publish job
4. ✅ Publish packages to npm

Step 6: Verify Publication

# Check npm registry
npm view @ruvector/core versions
npm view ruvector-core-darwin-arm64 versions

# Or search npm
npm search @ruvector

Option 2: Quick Release from PR

If you have a PR with passing builds:

# 1. Update version
npm version patch -w npm/core

# 2. Commit and push
git add -A
git commit -m "chore: bump version to X.Y.Z"
git push

# 3. Create and push tag
git tag vX.Y.Z
git push origin vX.Y.Z

Option 3: Release After Merge

# 1. Merge PR to main
gh pr merge <PR-NUMBER> --squash

# 2. Pull latest
git checkout main
git pull

# 3. Create tag
git tag vX.Y.Z -a -m "Release vX.Y.Z"
git push origin vX.Y.Z

Version Management

Versioning Strategy

We follow Semantic Versioning:

• MAJOR (1.0.0): Breaking changes
• MINOR (0.1.0): New features, backwards compatible
• PATCH (0.0.1): Bug fixes, backwards compatible

Version Synchronization

Critical: All packages must use synchronized versions:

// npm/core/package.json
{
  "version": "0.1.2",
  "optionalDependencies": {
    "ruvector-core-darwin-arm64": "0.1.2",    // ← Must match
    "ruvector-core-darwin-x64": "0.1.2",      // ← Must match
    "ruvector-core-linux-arm64-gnu": "0.1.2", // ← Must match
    "ruvector-core-linux-x64-gnu": "0.1.2",   // ← Must match
    "ruvector-core-win32-x64-msvc": "0.1.2"   // ← Must match
  }
}

Pre-release Versions

For beta/alpha releases:

# Create pre-release version
npm version prerelease --preid=beta
# 0.1.1 -> 0.1.2-beta.0

git tag v0.1.2-beta.0
git push origin v0.1.2-beta.0

CI/CD Workflow

Workflow Triggers

The build workflow (.github/workflows/build-native.yml) triggers on:

1. Pull Requests to main

   • Builds all platforms
   • Does NOT publish

2. Pushes to main

   • Builds all platforms
   • Does NOT publish

3. Tags matching v*

   • Builds all platforms
   • PUBLISHES to npm ✅

Build Matrix

The workflow builds for 5 platforms in parallel:

matrix:
  settings:
    - host: ubuntu-22.04
      platform: linux-x64-gnu

    - host: ubuntu-22.04
      platform: linux-arm64-gnu

    - host: macos-15-intel
      platform: darwin-x64

    - host: macos-14
      platform: darwin-arm64

    - host: windows-2022
      platform: win32-x64-msvc

Publish Job

The publish job runs only on tags:

publish:
  needs: build
  if: startsWith(github.ref, 'refs/tags/v')
  steps:
    - Download all artifacts
    - Copy binaries to platform packages
    - Publish platform packages
    - Publish main package

Workflow Files

.github/workflows/
├── build-native.yml      # Main build & publish workflow
└── agentic-synth-ci.yml  # Additional CI checks

Manual Publishing

If you need to publish manually (not recommended):

Prerequisites

# Login to npm
npm login

# Verify authentication
npm whoami

Build All Platforms

You'll need access to all 5 platforms or use cross-compilation:

# Linux x64
cargo build --release --target x86_64-unknown-linux-gnu

# Linux ARM64
cargo build --release --target aarch64-unknown-linux-gnu

# macOS Intel
cargo build --release --target x86_64-apple-darwin

# macOS ARM64
cargo build --release --target aarch64-apple-darwin

# Windows
cargo build --release --target x86_64-pc-windows-msvc

Publish Platform Packages

cd npm/core/platforms

# Publish each platform
cd darwin-arm64 && npm publish --access public
cd ../darwin-x64 && npm publish --access public
cd ../linux-arm64-gnu && npm publish --access public
cd ../linux-x64-gnu && npm publish --access public
cd ../win32-x64-msvc && npm publish --access public

Publish Main Package

cd npm/core
npm run build  # Compile TypeScript
npm publish --access public

Troubleshooting

Build Failures

Issue: Version Mismatch Error

npm error Invalid: lock file's ruvector-core-darwin-arm64@0.1.1
does not satisfy ruvector-core-darwin-arm64@0.1.2

Solution: Synchronize versions in npm/core/package.json:

# Update optionalDependencies to match platform package versions
cd npm
npm install
git add package-lock.json
git commit -m "fix: sync package versions"

Issue: macOS Build Failures

Error: macos-13 runner deprecated

Solution: Update workflow to use macos-15-intel:

- host: macos-15-intel  # Not macos-13
  platform: darwin-x64

Issue: Windows PowerShell Errors

Could not find a part of the path 'D:\dev\null'

Solution: Add shell: bash to Windows-compatible steps:

- name: Find built .node files
  shell: bash  # ← Add this
  run: |
    find . -name "*.node" 2>/dev/null || true

Publishing Failures

Issue: NPM Authentication Failed

npm error code ENEEDAUTH
npm error need auth This command requires you to be logged in

Solution:

1. Verify NPM_TOKEN secret in GitHub repository settings
2. Regenerate token if expired: https://www.npmjs.com/settings/[username]/tokens
3. Update repository secret

Issue: Permission Denied

npm error code E403
npm error 403 Forbidden - PUT https://registry.npmjs.org/@ruvector%2fcore

Solution:

1. Verify you have publish permissions for @ruvector scope
2. Contact npm org admin to grant permissions
3. Ensure package name is available on npm

Issue: Build Artifacts Not Found

Error: No files were found with the provided path: npm/core/platforms/*/

Solution:

1. Check that all 5 builds completed successfully
2. Verify artifact upload step succeeded
3. Check artifact names match expected pattern: bindings-{platform}

Version Issues

Issue: Tag Already Exists

error: tag 'v0.1.2' already exists

Solution:

# Delete local tag
git tag -d v0.1.2

# Delete remote tag
git push origin :refs/tags/v0.1.2

# Create tag again
git tag v0.1.2
git push origin v0.1.2

Issue: Wrong Version Published

If you published the wrong version:

# Deprecate the bad version
npm deprecate @ruvector/core@0.1.2 "Incorrect version, use 0.1.3"

# Unpublish (only within 72 hours)
npm unpublish @ruvector/core@0.1.2

# Publish correct version
git tag v0.1.3
git push origin v0.1.3

Post-Publication

Verify Published Packages

# Check versions
npm view @ruvector/core versions
npm view ruvector-core-darwin-arm64 versions

# Test installation
npm create vite@latest test-project
cd test-project
npm install @ruvector/core
npm run dev

Update Documentation

After publishing:

1. Update CHANGELOG.md with release notes
2. Update README.md version badges
3. Create GitHub Release with notes
4. Update documentation site if applicable

Create GitHub Release

# Using gh CLI
gh release create v0.1.2 \
  --title "Release v0.1.2" \
  --notes "## Changes

- Feature 1
- Feature 2
- Bug fix 3

**Full Changelog**: https://github.com/ruvnet/ruvector/compare/v0.1.1...v0.1.2"

# Or create manually at:
# https://github.com/ruvnet/ruvector/releases/new

Announce Release

• Post on social media
• Update project website
• Notify users on Discord/Slack
• Send newsletter if applicable

Release Checklist

Use this checklist for each release:

## Pre-Release
- [ ] All tests passing
- [ ] All 5 platform builds passing
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] Version bumped in package.json
- [ ] Version synchronized across all packages

## Release
- [ ] Version committed and pushed
- [ ] Git tag created
- [ ] Tag pushed to trigger workflow
- [ ] Workflow completed successfully
- [ ] Packages published to npm

## Post-Release
- [ ] Verified packages on npm
- [ ] Test installation works
- [ ] GitHub Release created
- [ ] Documentation updated
- [ ] Announced release

Additional Resources

• npm Publishing Documentation
• Semantic Versioning
• GitHub Actions Documentation
• NAPI-RS Documentation
• Rust Cross-Compilation

Support

If you encounter issues not covered in this guide:

1. Check GitHub Issues
2. Review GitHub Actions Logs
3. Ask in Discussions
4. Contact maintainers

---

Last Updated: 2025-11-25 Version: 1.0.0