crate publishing workflow

.github/PUBLISH_CRATES.md

@@ -0,0 +1,104 @@
+# Release Process
+
+Publishing DiskANN crates to [crates.io](https://crates.io).
+
+## Overview
+
+All workspace crates are published together with synchronized version numbers using `cargo publish --workspace`, which automatically resolves dependency order and waits for each crate to be indexed before publishing its dependents. The release is triggered by pushing a version tag. The Rust toolchain version is read from [`rust-toolchain.toml`](../../rust-toolchain.toml).
+
+## Prerequisites
+
+1. **CRATES_IO_TOKEN Secret**: A crates.io API token configured as a GitHub repository secret named `CRATES_IO_TOKEN` with publish permissions for all DiskANN crates.
+   - Create a token: [crates.io/settings/tokens](https://crates.io/settings/tokens)
+   - Add the secret: Repository Settings → Secrets and variables → Actions → New repository secret
+
+2. **Maintainer Access**: Write access to the repository and owner/maintainer of all crates on crates.io.
+
+## Dry-Run Testing
+
+**Always test before publishing a real release.**
+
+### Option 1: GitHub Actions (Recommended)
+
+1. Navigate to: `https://github.com/microsoft/DiskANN/actions/workflows/publish.yml`
+2. Click **Run workflow**, select your branch, keep **dry-run = true**
+3. Watch the workflow — look for successful `cargo publish --workspace --dry-run`
+
+### Option 2: Local
+
+```bash
+cargo publish --locked --workspace --dry-run
+```
+
+### What Dry-Run Tests
+
+- Crate metadata and packaging validation
+- Dependency resolution and publish ordering
+- Build verification
+
+### What It Does NOT Test
+
+- Actual publishing, registry token auth, upload reliability
+
+## Release Steps
+
+1. **Update version** in root `Cargo.toml`:
+
+   ```toml
+   [workspace.package]
+   version = "0.46.0"
+   ```
+
+   All workspace crates inherit this via `version.workspace = true`.
+
+2. **Update CHANGELOG** (if applicable).
+
+3. **Run dry-run** on a branch to validate (see above).
+
+4. **Tag and push**:
+
+   ```bash
+   git tag v0.46.0
+   git push origin v0.46.0
+   ```
+
+   Tag format: `v{major}.{minor}.{patch}`
+
+5. **Monitor** the workflow in the Actions tab.
+
+6. **Verify**:
+
+   ```bash
+   cargo search diskann --limit 20
+   ```
+
+### Example Pre-Release Flow
+
+```bash
+# Update version
+vim Cargo.toml  # Change to 0.46.0
+
+# Commit to a branch (don't tag yet)
+git checkout -b release-0.46.0
+git commit -am "Bump version to 0.46.0"
+git push origin release-0.46.0
+
+# Run dry-run via GitHub Actions UI on release-0.46.0
+
+# If successful, merge and tag
+git checkout main
+git merge release-0.46.0
+git tag v0.46.0
+git push origin main --tags  # Triggers the real publish
+```
+
+## Pre-release Checklist
+
+- [ ] All CI checks pass on the main branch
+- [ ] Version number is updated in `Cargo.toml`
+- [ ] CHANGELOG is updated (if applicable)
+- [ ] Documentation is up to date
+- [ ] Breaking changes are clearly documented
+- [ ] All tests pass locally: `cargo test --workspace`
+- [ ] Code builds without warnings: `cargo build --workspace --release`
+- [ ] **Dry-run workflow test passes successfully**

.github/workflows/publish.yml

@@ -0,0 +1,81 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT license.
+
+# Publishes all workspace crates to crates.io.
+# Triggered by pushing a version tag (v{major}.{minor}.{patch}) or manually via workflow_dispatch.
+# Requires CRATES_IO_TOKEN secret. Rust toolchain version is read from rust-toolchain.toml.
+
+name: Publish to crates.io
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Run in dry-run mode (test without actually publishing)'
+        required: false
+        default: 'true'
+        type: choice
+        options:
+          - 'true'
+          - 'false'
+
+env:
+  RUST_BACKTRACE: 1
+
+defaults:
+  run:
+    shell: bash
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: ${{ github.event.inputs.dry_run == 'true' && 'Dry-run publish test' || 'Publish crates to crates.io' }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          lfs: true
+
+      - name: Read Rust version from rust-toolchain.toml
+        id: rust-version
+        run: |
+          RUST_VERSION=$(sed -n 's/^channel = "\(.*\)"/\1/p' rust-toolchain.toml)
+          echo "channel=$RUST_VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Install Rust ${{ steps.rust-version.outputs.channel }}
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: ${{ steps.rust-version.outputs.channel }}
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Verify version matches tag
+        if: github.event_name == 'push'
+        run: |
+          TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+          CARGO_VERSION=$(grep '^version = ' Cargo.toml | head -n1 | sed 's/.*"\(.*\)".*/\1/')
+          if [ "$TAG_VERSION" != "$CARGO_VERSION" ]; then
+            echo "::error::Tag version ($TAG_VERSION) does not match Cargo.toml version ($CARGO_VERSION)"
+            exit 1
+          fi
+
+      - name: Run tests
+        run: cargo test --locked --workspace --profile ci
+
+      - name: Publish workspace crates
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CRATES_IO_TOKEN }}
+        run: |
+          DRY_RUN_FLAG=""
+          if [ "${{ github.event.inputs.dry_run || 'false' }}" = "true" ]; then
+            DRY_RUN_FLAG="--dry-run"
+            echo "🧪 DRY-RUN MODE"
+          fi
+          cargo publish --locked --workspace $DRY_RUN_FLAG