# Releasing garage-sdk
This document describes how to release a new version of garage-sdk.
## Prerequisites
1. You have push access to the repository
2. The `CARGO_REGISTRY_TOKEN` secret is configured in GitHub (Settings → Secrets → Actions)
3. A GitHub environment called `crates-io` exists (Settings → Environments)
4. Rust 1.92 or newer is installed (MSRV)
## Release Steps
### 1. Prepare the Release
1. **Update version in `Cargo.toml`:**
```toml
[package]
version = "X.Y.Z" # New version
```
2. **Update `CHANGELOG.md`:**
- Move items from `[Unreleased]` to `[X.Y.Z] - YYYY-MM-DD`
- Add a new empty `[Unreleased]` section at the top
- Update the links at the bottom of the file
3. **Commit and push:**
```bash
git add Cargo.toml CHANGELOG.md
git commit -m "chore: prepare release vX.Y.Z"
git push origin main
```
### 2. Trigger the Release
1. Go to **Actions** → **Release** workflow
2. Click **Run workflow**
3. Enter the version (e.g., `0.2.0`)
4. Optionally enable **Dry run** to test first
5. Click **Run workflow**
### 3. What the Workflow Does
1. **Validate** - Checks version format and Cargo.toml
2. **Test** - Runs full test suite, clippy, and formatting checks
3. **Publish** - Publishes to crates.io
4. **Release** - Creates Git tag and GitHub Release with changelog
### 4. After Release
- Verify the crate appears on [crates.io](https://crates.io/crates/garage-sdk)
- Verify docs are published on [docs.rs](https://docs.rs/garage-sdk)
- Verify the GitHub Release was created with correct changelog
## Versioning
This project follows [Semantic Versioning](https://semver.org/):
- **MAJOR** (X.0.0): Breaking API changes
- **MINOR** (0.X.0): New features, backward compatible
- **PATCH** (0.0.X): Bug fixes, backward compatible
### Pre-release Versions
For pre-releases, use suffixes like:
- `1.0.0-alpha.1`
- `1.0.0-beta.1`
- `1.0.0-rc.1`
## MSRV
This project targets Rust 1.92 (Edition 2024). Update the MSRV in `Cargo.toml`
and `.github/workflows/ci.yml` together.
## Changelog Workflow
The GitHub release body is generated from the `CHANGELOG.md` section that matches
the version you pass to the release workflow. Keep entries under `[Unreleased]`
and promote them into a dated release section right before publishing.
Checklist:
- Ensure there is a `## [Unreleased]` section at the top
- Add a `## [X.Y.Z] - YYYY-MM-DD` section with the changes you’re releasing
- Verify the version matches `Cargo.toml`
## Troubleshooting
### "Version in Cargo.toml doesn't match"
Update `Cargo.toml` with the correct version and push before releasing.
### "Tag already exists"
The version was already released. Bump to a new version.
### Publish failed
1. Check the `CARGO_REGISTRY_TOKEN` secret is valid
2. Ensure the crate name isn't taken
3. Review cargo publish error messages in the workflow logs
### Rollback a Release
You cannot delete a version from crates.io, but you can yank it:
```bash
cargo yank --version X.Y.Z
```
This hides it from new installations but doesn't break existing users.
## Setting Up Secrets
### CARGO_REGISTRY_TOKEN
1. Go to [crates.io](https://crates.io) → Account Settings → API Tokens
2. Create a new token with publish permissions
3. In GitHub: Settings → Secrets → Actions → New repository secret
4. Name: `CARGO_REGISTRY_TOKEN`, Value: your token
### GitHub Environment (Optional but Recommended)
1. Go to Settings → Environments → New environment
2. Name: `crates-io`
3. Add protection rules:
- Require reviewers (optional)
- Restrict to `main` branch