Skip to content

PUBLISH.md

Latest commit

 

History

History
364 lines (268 loc) · 7.79 KB

PUBLISH.md

File metadata and controls

364 lines (268 loc) · 7.79 KB

Publishing RpcNet with Makefile

Quick reference guide for publishing RpcNet to crates.io using Makefile targets.

Quick Start

# 1. Update version and docs
vim Cargo.toml CHANGELOG.md README.md

# 2. Commit and tag
git add -A
git commit -m "chore: bump version to 0.2.0"
git tag -a v0.2.0 -m "Release version 0.2.0"

# 3. Check everything is ready
make publish-check

# 4. Dry run (see what will be published)
make publish-dry-run

# 5. Publish!
make publish

Makefile Targets

make publish-check

Runs all pre-publication checks to ensure the package is ready:

✅ Tests (all features)
✅ Code formatting
✅ Linter (clippy with warnings as errors)
✅ Documentation build
⚠️ Coverage check (warning only)

When to use: Before making any publication attempt, or during development to ensure quality.

Example output:

=== Pre-Publication Checks ===

1. Verifying all tests pass...
✅ All tests passed

2. Checking code formatting...
✅ Code is properly formatted

3. Running linter...
✅ No clippy warnings

4. Building documentation...
✅ Documentation builds successfully

5. Checking coverage...
✅ Coverage 92.3% meets threshold

✅ All pre-publication checks passed!

make publish-dry-run

Packages the crate and shows what files will be published:

  1. Runs publish-check first
  2. Lists all files that will be included
  3. Creates package in target/package/
  4. Does NOT publish to crates.io

When to use: Before actual publication to verify package contents.

Example output:

=== Packaging rpcnet (library + rpcnet-gen CLI) ===

Reviewing package contents...
Cargo.toml
README.md
LICENSE-MIT
LICENSE-APACHE
src/lib.rs
src/cluster/mod.rs
...

Building package...
✅ Package created successfully!

Package location: target/package/rpcnet-0.2.0.crate

To publish, run: make publish

make publish

Publishes to crates.io with safety confirmation:

  1. Runs publish-check first
  2. Asks for confirmation (you must type "yes")
  3. Publishes to crates.io
  4. Shows next steps after success

When to use: When you're ready to publish and have verified everything.

Example output:

=== Publishing to crates.io ===

⚠️  WARNING: This action cannot be undone!

Are you sure you want to publish rpcnet v0.2.0? (yes/no): yes

Publishing rpcnet crate (library + rpcnet-gen CLI)...
    Uploading rpcnet v0.2.0
✅ Successfully published to crates.io!

Next steps:
  1. Push to GitHub: git push origin main
  2. Push tag: git push origin v0.2.0
  3. Create GitHub release: https://github.com/jsam/rpcnet/releases/new
  4. Verify on crates.io: https://crates.io/crates/rpcnet
  5. Check docs.rs: https://docs.rs/rpcnet

Complete Workflow

Recommended: Safe and Verified

# Step 1: Prepare release
vim Cargo.toml          # Update version
vim CHANGELOG.md        # Add release notes
vim README.md           # Update if needed

# Step 2: Commit changes
git add Cargo.toml CHANGELOG.md README.md
git commit -m "chore: prepare v0.2.0 release"
git tag -a v0.2.0 -m "Release version 0.2.0"

# Step 3: Pre-publication checks
make publish-check
# Wait for all checks to pass

# Step 4: Verify package contents (IMPORTANT!)
make publish-dry-run
# Review the file list carefully

# Step 5: Publish
make publish
# Type "yes" when prompted

# Step 6: Push to GitHub
git push origin main
git push origin v0.2.0

# Step 7: Verify publication
# - Visit https://crates.io/crates/rpcnet
# - Test: cargo install rpcnet && rpcnet-gen --help
# - Check https://docs.rs/rpcnet/0.2.0

Quick: For Experienced Publishers

vim Cargo.toml CHANGELOG.md
git add -A && git commit -m "chore: bump v0.2.0" && git tag -a v0.2.0 -m "v0.2.0"
make publish  # Runs checks automatically
git push origin main && git push origin v0.2.0

What Gets Checked

The publish-check target verifies:

1. Tests (Critical)

cargo test --all-features
  • All 183+ tests must pass
  • Tests both library and integration tests
  • Includes cluster and streaming tests

2. Code Formatting (Critical)

cargo fmt --check
  • Code must follow Rust formatting standards
  • Run make format if this fails

3. Linter (Critical)

cargo clippy --all-targets --all-features -- -D warnings
  • No clippy warnings allowed
  • Treats warnings as errors
  • Ensures code quality

4. Documentation (Critical)

cargo doc --no-deps --all-features
  • Documentation must build without errors
  • Ensures docs.rs will build successfully

5. Coverage (Warning Only)

make coverage-check
  • Checks for 90%+ coverage
  • Only warns if it fails (doesn't block)

Troubleshooting

Tests Fail

# Run tests to see failures
cargo test --all-features

# Fix the failing tests
vim src/...

# Re-run checks
make publish-check

Formatting Issues

# Auto-format code
make format

# Or manually
cargo fmt

# Verify
make publish-check

Clippy Warnings

# See warnings
cargo clippy --all-targets --all-features

# Fix warnings
vim src/...

# Re-check
make publish-check

Documentation Errors

# Build docs to see errors
cargo doc --all-features

# Fix doc comments
vim src/...

# Verify
make publish-check

Cancel Publication

If you accidentally start make publish:

  1. Before typing "yes": Just type "no" or press Ctrl+C
  2. After typing "yes": Cannot cancel - publish completes immediately
  3. After published: Cannot delete - can only yank version

Safety Features

The Makefile publish targets include multiple safety features:

✅ Automatic checks: Runs tests, lint, format before publishing
✅ Confirmation prompt: Must type "yes" to proceed
✅ Dry run option: publish-dry-run lets you verify first
✅ Clear output: Shows what's happening at each step
✅ Next steps: Reminds you to push tags and create release
⚠️ No undo warning: Clearly states action cannot be undone

Files Published

When you run make publish, these files are included:

Core Library:

  • src/**/*.rs - All source code
  • Cargo.toml - Package metadata
  • LICENSE-MIT, LICENSE-APACHE - Licenses

Documentation:

  • README.md - Project overview
  • DEVELOPER.md - Development guide
  • TESTING.md - Testing guide

Examples:

  • examples/**/* - All examples including cluster
  • examples/cluster/README.md - Cluster setup guide

Tests & Benchmarks:

  • tests/**/*.rs - Test suites
  • benches/**/*.rs - Benchmarks

Certificates:

  • certs/test_*.pem - Test certificates (dev only)

CLI Tool Included

Important: Starting with v0.2.0, the rpcnet-gen CLI is included by default!

Users get both:

  1. The library (via Cargo.toml dependency)
  2. The CLI tool (via cargo install rpcnet)

No feature flags needed - it just works! 🎉

Post-Publication

After make publish succeeds:

Immediate (Required)

git push origin main
git push origin v0.2.0

Create GitHub Release (Required)

  1. Go to https://github.com/jsam/rpcnet/releases/new
  2. Select tag v0.2.0
  3. Title: v0.2.0
  4. Copy release notes from CHANGELOG.md
  5. Publish release

Verify (Recommended)

  1. Check crates.io: https://crates.io/crates/rpcnet
  2. Wait for docs.rs: https://docs.rs/rpcnet/0.2.0
  3. Test installation: 
    cargo install rpcnet
rpcnet-gen --help

Announce (Optional)

  • Post to Reddit r/rust
  • Submit to This Week in Rust
  • Tweet/social media
  • Blog post

Additional Commands

Other useful Makefile targets:

make help           # Show all available targets
make test           # Run all tests
make lint           # Run clippy
make format         # Format code
make doc            # Build and open docs
make bench          # Run benchmarks
make clean          # Clean build artifacts

Quick Reference: make publish-check → make publish-dry-run → make publish