Skip to content

PUBLISHING.md

Latest commit

 

History

History
403 lines (278 loc) · 7.34 KB

PUBLISHING.md

File metadata and controls

403 lines (278 loc) · 7.34 KB

Publishing Solisp to crates.io

This guide explains how to publish the Solisp crate to crates.io.

Prerequisites

  1. Crates.io Account

  2. GitHub Secret

    • Add CARGO_REGISTRY_TOKEN to repository secrets
    • Settings → Secrets and variables → Actions → New repository secret

  3. Cargo.toml Verification

    • Ensure all metadata is correct (version, description, license, etc.)
    • Verify dependencies are properly specified

Publishing Methods

Method 1: Automatic via GitHub Actions (Recommended)

Step 1: Update Version

Edit crates/solisp/Cargo.toml:

[package]
version = "1.0.1"  # Increment version

Step 2: Update Changelog

Edit crates/solisp/CHANGELOG.md:

## [1.0.1] - 2025-10-11

### Added
- New feature X
- New feature Y

### Fixed
- Bug fix A
- Bug fix B

Step 3: Commit Changes

git add crates/solisp/Cargo.toml crates/solisp/CHANGELOG.md
git commit -m "chore(solisp): bump version to 1.0.1"
git push origin main

Step 4: Create Git Tag

git tag solisp-v1.0.1
git push origin solisp-v1.0.1

This will automatically trigger the GitHub Actions workflow that:

  1. ✅ Runs all tests
  2. ✅ Verifies formatting and linting
  3. ✅ Tests all examples
  4. ✅ Publishes to crates.io
  5. ✅ Creates GitHub Release
  6. ✅ Deploys documentation

Step 5: Verify Publication

Check:

Method 2: Manual Publication

Step 1: Verify Everything Works

cd crates/solisp

# Check formatting
cargo fmt --all -- --check

# Run clippy
cargo clippy --all-targets --all-features -- -D warnings

# Run all tests
cargo test

# Test examples
cargo run --example run_file examples/hello_world.solisp

Step 2: Verify Package

# Dry run to check what will be published
cargo package --allow-dirty

# Check the generated package
cd target/package
tar -xzf solisp-*.crate
ls -la solisp-*/

Step 3: Publish

cd crates/solisp
cargo publish --token YOUR_TOKEN_HERE

Or with token from environment:

export CARGO_REGISTRY_TOKEN="your-token-here"
cargo publish

Method 3: Dry Run (Testing Only)

Test the publishing workflow without actually publishing:

# Via GitHub Actions UI
# Go to Actions → Publish Solisp Crate → Run workflow
# Set "Dry run" to "true"

# Or manually
cd crates/solisp
cargo publish --dry-run --allow-dirty

Version Numbering

Follow Semantic Versioning:

  • MAJOR version (1.x.x → 2.0.0): Breaking changes
  • MINOR version (1.0.x → 1.1.0): New features, backward compatible
  • PATCH version (1.0.0 → 1.0.1): Bug fixes, backward compatible

Examples

# Bug fix release
version = "1.0.0" → "1.0.1"

# New feature (backward compatible)
version = "1.0.1" → "1.1.0"

# Breaking changes
version = "1.1.0" → "2.0.0"

Pre-Release Checklist

Before publishing, verify:

  • All tests pass: cargo test
  • Examples work: Test all .solisp scripts
  • Documentation builds: cargo doc --no-deps
  • Package builds: cargo package --allow-dirty
  • Version bumped in Cargo.toml
  • CHANGELOG.md updated
  • README.md accurate
  • License file present (LICENSE or LICENSE-MIT)
  • No sensitive data in repository

Post-Release Tasks

After successful publication:

  1. Verify on crates.io

    https://crates.io/crates/solisp/1.0.1

  2. Check documentation

    https://docs.rs/solisp/1.0.1

  3. Test installation

    cargo install solisp --version 1.0.1

  4. Announce release

    • Update main README.md
    • Social media / Discord / Telegram
    • Release notes on GitHub

  5. Monitor for issues

    • Check GitHub issues
    • Monitor crates.io download stats

Troubleshooting

Error: Version Already Published

Problem: error: crate version 1.0.0 is already uploaded

Solution: Bump version in Cargo.toml - you cannot re-publish the same version.

version = "1.0.1"  # Increment version

Error: Missing License File

Problem: error: missing license file

Solution: Ensure LICENSE or LICENSE-MIT file exists:

cd crates/solisp
# If missing, copy from root
cp ../../LICENSE .

Error: Documentation Build Failed

Problem: cargo doc fails

Solution: Fix documentation errors:

# Check what's wrong
cargo doc --no-deps

# Common issues:
# - Missing doc comments on public items
# - Broken doc links
# - Code examples that don't compile

Error: Package Too Large

Problem: error: package size exceeds limit

Solution: Exclude unnecessary files in Cargo.toml:

[package]
exclude = [
    "tests/fixtures/*",
    "benches/data/*",
    "docs/*",
    "*.md",
    "!README.md",
    "!CHANGELOG.md",
]

Error: Authentication Failed

Problem: error: authentication failed

Solution: Check your token:

# Verify token is set
echo $CARGO_REGISTRY_TOKEN

# Or use explicit token
cargo publish --token YOUR_TOKEN_HERE

# Or login interactively
cargo login

Yanking a Release

If you need to remove a published version:

# Yank version (prevents new projects from using it)
cargo yank --vers 1.0.1

# Unyank if you change your mind
cargo yank --vers 1.0.1 --undo

Note: Yanking doesn't delete; existing users can still use it.

CI/CD Pipeline Details

Workflow Triggers

The publish workflow (publish-solisp.yml) triggers on:

  1. Git tags: solisp-v* (e.g., solisp-v1.0.1)
  2. Manual: Via GitHub Actions UI

Workflow Steps

  1. Verify and Test

    • Check formatting
    • Run clippy
    • Build release binary
    • Run all tests
    • Test all examples
    • Generate docs
    • Verify package

  2. Publish

    • Extract version from tag
    • Verify version matches Cargo.toml
    • Publish to crates.io (or dry-run)
    • Create GitHub release

  3. Deploy Docs

    • Generate documentation
    • Deploy to GitHub Pages

  4. Notify

    • Print success message with links

Maintenance

Regular Updates

  • Dependencies: Update monthly with cargo update
  • Rust toolchain: Test with latest stable
  • Security: Run cargo audit regularly
  • Documentation: Keep examples and guides current

Long-Term Support

  • Maintain changelog
  • Respond to issues promptly
  • Tag releases appropriately
  • Keep documentation accurate

Additional Resources

Quick Reference

# Update version
vim crates/solisp/Cargo.toml

# Update changelog
vim crates/solisp/CHANGELOG.md

# Commit and tag
git add crates/solisp/Cargo.toml crates/solisp/CHANGELOG.md
git commit -m "chore(solisp): bump version to X.Y.Z"
git push origin main
git tag solisp-vX.Y.Z
git push origin solisp-vX.Y.Z

# Manual publish (if needed)
cd crates/solisp
cargo publish

# Verify
open https://crates.io/crates/solisp
open https://docs.rs/solisp

Need help? Open an issue or contact the maintainers.