# Publishing screenshotfreeapi to crates.io
Step-by-step guide for maintainers.
---
## Prerequisites
| Rust stable | `rustup update stable` |
| cargo-release | `cargo install cargo-release` |
| git | Any recent version |
---
## Step 1 — Create a crates.io account
1. Go to <https://crates.io> and sign in with GitHub.
2. Navigate to **Account Settings → API Tokens**.
3. Click **New Token**, name it (e.g. `screenshotfreeapi-publish`), and copy it.
The token is shown **once** — store it securely.
---
## Step 2 — Log in to crates.io locally
```bash
cargo login
# Paste your API token when prompted
```
This writes your token to `~/.cargo/credentials.toml`.
---
## Step 3 — Verify `Cargo.toml` metadata
Before publishing, confirm the following fields in `Cargo.toml` are correct:
- `version` — follows [Semantic Versioning](https://semver.org) (`MAJOR.MINOR.PATCH`)
- `description` — one-line description
- `license` — `"MIT"` or `"MIT OR Apache-2.0"`
- `repository` — GitHub URL
- `documentation` — `"https://docs.rs/screenshotfreeapi"`
- `keywords` — up to 5 keywords
- `categories` — up to 5 valid [crates.io categories](https://crates.io/category_slugs)
- `rust-version` — minimum supported Rust version
---
## Step 4 — Run a dry-run publish
```bash
cd sdks/rust
cargo publish --dry-run
```
This bundles the crate and verifies it can be uploaded **without** actually
publishing. Fix any warnings before continuing.
---
## Step 5 — Review the generated documentation
```bash
cargo doc --open
```
Browse the docs locally to catch missing doc-comments, broken links, or
examples that don't compile.
---
## Step 6 — Publish
```bash
cargo publish
```
crates.io processes the upload within ~30 seconds. The new version will be
visible at `https://crates.io/crates/screenshotfreeapi`.
---
## Step 7 — Verify on crates.io
1. Open `https://crates.io/crates/screenshotfreeapi`.
2. Confirm the correct version is listed.
3. Open `https://docs.rs/screenshotfreeapi` — docs.rs will start building
automatically (takes 1–5 minutes).
---
## Step 8 — Tag the release
```bash
git tag v1.0.0
git push origin v1.0.0
```
The GitHub Actions workflow (`.github/workflows/publish.yml`) triggers on `v*`
tags, runs the full CI suite, and then publishes automatically. The manual
`cargo publish` in step 6 is only needed for the very first release or for
emergency hotfixes outside CI.
---
## Step 9 — Using cargo-release (recommended for future releases)
`cargo-release` automates the version bump, git tag, and publish in one command:
```bash
# Bump patch version (1.0.0 → 1.0.1), tag, and publish
cargo release patch
# Bump minor version (1.0.0 → 1.1.0)
cargo release minor
# Bump major version (1.0.0 → 2.0.0)
cargo release major
```
Add a `release.toml` at the crate root to customise behaviour (pre/post hooks,
sign-off confirmation, etc.).
---
## Yanking a broken release
If a published version contains a critical bug:
```bash
# Yank the broken version
cargo yank --version 1.0.0
# Undo a yank if you change your mind
cargo yank --version 1.0.0 --undo
```
> **Note:** Yanking prevents new projects from depending on the version but
> does **not** break existing projects that already depend on it.
---
## Automated CI workflow
The file `.github/workflows/publish.yml` provides:
| Push to `main` / any PR | `cargo fmt --check`, `cargo clippy -D warnings`, `cargo test`, `cargo doc` |
| Push of a `v*.*.*` tag | All of the above, then `cargo publish` |
### Required GitHub secret
| `CARGO_REGISTRY_TOKEN` | crates.io API token (from Step 1) |
Add it under **Repository → Settings → Secrets and variables → Actions → New repository secret**.