Skip to content

PUBLISHING.md

Latest commit

 

History

History
149 lines (102 loc) · 3.28 KB

PUBLISHING.md

File metadata and controls

149 lines (102 loc) · 3.28 KB

Publishing Guide for api-guidelines

This guide will help you publish your api-guidelines crate to crates.io.

Prerequisites

  1. Crates.io Account: You need an account on crates.io
  2. API Token: Get your API token from your crates.io account settings
  3. Cargo Login: Run cargo login with your API token

Step-by-Step Publishing Process

1. Prepare Your Crate

Make sure your crate is ready for publishing:

# Build the crate to check for errors
cargo build

# Run tests
cargo test

# Check documentation
cargo doc --open

# Run clippy for code quality
cargo clippy

# Check formatting
cargo fmt -- --check

2. Verify Package Metadata

Your Cargo.toml should include:

  • name - "api-guidelines" ✓
  • version - "0.1.0" ✓
  • description - Added ✓
  • license - "MIT" ✓
  • repository - GitHub URL ✓
  • documentation - docs.rs URL ✓
  • readme - "README.md" ✓
  • keywords - Added ✓
  • categories - Added ✓

3. Login to Crates.io

# Login with your API token
cargo login

You'll be prompted to enter your API token from crates.io.

4. Dry Run (Optional but Recommended)

# Check if your package can be published without actually publishing
cargo publish --dry-run

This will validate your package without uploading it.

5. Publish the Crate

# Publish to crates.io
cargo publish

6. Verify Publication

After publishing:

  1. Visit https://crates.io/crates/api-guidelines
  2. Check that your documentation appears at https://docs.rs/api-guidelines

Post-Publishing Tasks

Version Management

After publishing, you cannot modify or delete published versions. To make changes:

  1. Bug Fixes: Bump patch version (0.1.0 → 0.1.1)
  2. New Features: Bump minor version (0.1.0 → 0.2.0)
  3. Breaking Changes: Bump major version (0.1.0 → 1.0.0)

Git Tagging

It's good practice to tag releases:

git tag v0.1.0
git push origin v0.1.0

Common Issues and Solutions

Name Already Taken

If "api-guidelines" is taken, you'll need to choose a different name in Cargo.toml.

Missing Metadata

Ensure all required fields in Cargo.toml are filled.

Documentation Build Failures

Make sure your code compiles and all doc tests pass.

License File Issues

Ensure LICENSE file exists and matches the license specified in Cargo.toml.

Best Practices

  1. Semantic Versioning: Follow semver.org for versioning
  2. Changelog: Consider adding a CHANGELOG.md file
  3. CI/CD: Set up GitHub Actions for automated testing and publishing
  4. Documentation: Keep documentation up to date
  5. Dependencies: Keep dependencies minimal and up to date

Next Steps

After successful publication:

  1. Share your crate with the Rust community
  2. Monitor downloads and issues
  3. Consider adding more API guideline categories
  4. Add utility functions for working with the guidelines
  5. Create examples and tutorials

Useful Commands

# Check crate info
cargo package --list

# Update dependencies
cargo update

# Check for outdated dependencies  
cargo outdated

# Generate lockfile (if needed)
cargo generate-lockfile

Support

If you encounter issues: