# Publishing Guide for wtcat
This guide walks you through publishing wtcat to GitHub and crates.io.
## Prerequisites
1. **GitHub account** - https://github.com
2. **crates.io account** - https://crates.io (sign in with GitHub)
3. **Git configured** with your credentials
4. **Cargo installed** (part of Rust toolchain)
## Step 1: Publish to GitHub
### 1.1 Create GitHub Repository
1. Go to https://github.com/new
2. Repository name: `wtcat`
3. Description: "WebTransport CLI client for testing - like wscat for WebSocket"
4. Public repository
5. **DO NOT** initialize with README, .gitignore, or license (we already have these)
6. Click "Create repository"
### 1.2 Update Repository URL in Code
Before pushing, update the placeholder URLs in `Cargo.toml`:
```toml
repository = "https://github.com/pervrosen/wtcat"
homepage = "https://github.com/pervrosen/wtcat"
```
Replace `pervrosen` with your actual GitHub username.
Also update README.md URLs (search for `pervrosen` and replace).
```bash
# Quick find and replace (macOS/Linux)
sed -i '' 's/pervrosen/your-actual-username/g' Cargo.toml README.md
# Or manually edit the files
```
Commit the changes:
```bash
git add Cargo.toml README.md
git commit -m "Update repository URLs with actual GitHub username"
```
### 1.3 Push to GitHub
Follow the instructions from GitHub after creating the repository:
```bash
git remote add origin https://github.com/pervrosen/wtcat.git
git branch -M main
git push -u origin main
```
### 1.4 Configure Repository Settings (Optional but Recommended)
1. Go to your repository settings on GitHub
2. Add topics/tags: `webtransport`, `http3`, `quic`, `cli`, `rust`, `testing`
3. Update the "About" section with description and website
## Step 2: Publish to crates.io
### 2.1 Get crates.io API Token
1. Sign in to https://crates.io (use GitHub)
2. Go to Account Settings → API Tokens
3. Click "New Token"
4. Name it something like "wtcat-publishing"
5. Copy the token (you'll only see it once!)
### 2.2 Login to crates.io via Cargo
```bash
cargo login <your-api-token>
```
This stores your token in `~/.cargo/credentials.toml`.
### 2.3 Verify Package Before Publishing
Run these checks to ensure everything is ready:
```bash
# Build in release mode
cargo build --release
# Run all tests
cargo test
# Run clippy
cargo clippy --all-targets -- -D warnings
# Check the package
cargo package
# Dry run publish (doesn't actually publish)
cargo publish --dry-run
```
Fix any errors or warnings that appear.
### 2.4 Publish to crates.io
When everything looks good:
```bash
cargo publish
```
**Note**: Once published, you cannot delete or modify a version. You can only yank it (hide it from new users while existing users can still use it).
### 2.5 Verify Publication
1. Visit https://crates.io/crates/wtcat
2. Check that the README renders correctly
3. Verify all links work
4. Test installation: `cargo install wtcat`
## Step 3: Create GitHub Release
### 3.1 Tag the Release
```bash
git tag -a v0.1.0 -m "Initial release"
git push origin v0.1.0
```
### 3.2 Create Release on GitHub
1. Go to your repository on GitHub
2. Click "Releases" → "Create a new release"
3. Choose the tag: `v0.1.0`
4. Release title: `v0.1.0 - Initial Release`
5. Description:
```markdown
# wtcat v0.1.0
First public release of wtcat - WebTransport CLI client for testing.
## Features
- 🚀 Simple WebTransport connections
- 🔐 Flexible authentication (JWT, username/password, custom, or none)
- 📤 Custom JSON payload support
- 📡 Real-time message streaming
- 🔧 JSON mode for piping to jq
- 🔒 TLS options including self-signed certificate support
- ⚡ Built on QUIC/HTTP3
## Installation
```bash
cargo install wtcat
```
## Quick Start
```bash
# Simple connection
wtcat --url https://localhost:4433 --no-auth -k
# With JWT token
wtcat --url https://localhost:4433 --token "your-jwt" -k
# JSON mode
## Documentation
Full documentation available at:
- README: https://github.com/pervrosen/wtcat
- Docs.rs: https://docs.rs/wtcat
## What's Next
See [GitHub issues](https://github.com/pervrosen/wtcat/issues) for planned features.
```
6. Click "Publish release"
## Step 4: Update Documentation
### 4.1 Verify docs.rs
1. Go to https://docs.rs/wtcat
2. Wait for docs to build (can take a few minutes)
3. Verify documentation looks correct
4. Check that examples compile
### 4.2 Add Badges to README (Optional)
Add these to the top of README.md after publication:
```markdown
[](https://crates.io/crates/wtcat)
[](https://docs.rs/wtcat)
[](https://opensource.org/licenses/MIT)
[](https://crates.io/crates/wtcat)
```
Commit and push:
```bash
git add README.md
git commit -m "Add crates.io badges to README"
git push
```
## Step 5: Announce and Share
### 5.1 Share on Social Media
- Twitter/X: "Just published wtcat - a WebTransport CLI client for Rust! Like wscat but for WebTransport/HTTP3. Check it out: https://github.com/pervrosen/wtcat #rustlang #webtransport"
- Reddit r/rust: Create a post announcing the tool
- Rust Users Forum: https://users.rust-lang.org
### 5.2 Submit to Awesome Lists
Consider submitting to:
- awesome-rust: https://github.com/rust-unofficial/awesome-rust
- awesome-cli-apps: https://github.com/agarrharr/awesome-cli-apps
## Updating Versions
When you want to release a new version:
### 1. Update Version Number
Edit `Cargo.toml`:
```toml
[package]
version = "0.2.0" # Increment according to semver
```
### 2. Update CHANGELOG
Create `CHANGELOG.md` if you haven't already:
```markdown
# Changelog
## [0.2.0] - 2025-01-XX
### Added
- New feature X
- New feature Y
### Fixed
- Bug Z
### Changed
- Updated dependency A
## [0.1.0] - 2025-12-04
Initial release
```
### 3. Commit, Tag, and Publish
```bash
# Commit changes
git add Cargo.toml CHANGELOG.md
git commit -m "Bump version to 0.2.0"
# Create tag
git tag -a v0.2.0 -m "Release v0.2.0"
# Push
git push && git push --tags
# Publish to crates.io
cargo publish
```
### 4. Create GitHub Release
Follow Step 3.2 above with the new version number.
## Troubleshooting
### "crate name is already taken"
If `wtcat` is already taken on crates.io, you'll need to choose a different name:
1. Brainstorm alternatives: `wt-cat`, `webtransport-cat`, `wtcli`, `wt-client`, etc.
2. Check availability: https://crates.io/search?q=your-name
3. Update `name` in `Cargo.toml`
4. Update all references in code and documentation
5. Try publishing again
### "failed to verify package"
Run `cargo package` to see detailed errors. Common issues:
- Files excluded by `.gitignore` that shouldn't be
- Missing dependencies
- Path issues
### Documentation not building
Check https://docs.rs/crate/wtcat/latest/builds for build logs. Common issues:
- Broken example code in doc comments
- Missing dev-dependencies
- Feature flags not configured
## Best Practices
1. **Semantic Versioning**: Follow https://semver.org
- MAJOR: Breaking changes
- MINOR: New features (backwards compatible)
- PATCH: Bug fixes
2. **Keep CHANGELOG**: Document all changes between versions
3. **Test Before Publishing**: Always run full test suite
4. **Write Good Commit Messages**: Clear, descriptive messages
5. **Respond to Issues**: Be active in responding to user issues and PRs
6. **Security**: Watch for security advisories on dependencies
## Resources
- Cargo Book: https://doc.rust-lang.org/cargo/
- crates.io Guide: https://doc.rust-lang.org/cargo/reference/publishing.html
- Rust API Guidelines: https://rust-lang.github.io/api-guidelines/
- Keep a Changelog: https://keepachangelog.com/
## Questions?
- Open an issue on GitHub
- Ask in Rust community forums
- Check the Cargo book
---
Good luck with your publication! 🚀