Michel de Graaf
9c966672af
Add a release job that regenerates Formula/soulseek-rs.rb in michel/homebrew-tap from the archives the binaries matrix uploads, and lead with `brew install michel/tap/soulseek-rs` in the READMEs and on the website.
85 lines
4.6 KiB
Markdown
85 lines
4.6 KiB
Markdown
# Releasing
|
|
|
|
Releases are automated by [release-plz](https://release-plz.dev). You do not run
|
|
`cargo publish`, edit versions, write changelog entries, or push tags by hand.
|
|
|
|
## How it works
|
|
|
|
1. Merge a PR to `master` using [conventional commits](https://www.conventionalcommits.org)
|
|
(`feat:`, `fix:`, `perf:`, `refactor:`, `docs:`, `chore:`, or a `!` / `BREAKING CHANGE:`
|
|
footer for a major bump).
|
|
2. `.github/workflows/release.yml` opens or updates a **`chore: release vX.Y.Z`** PR. It
|
|
contains the semver bump in `[workspace.package]`, the refreshed `Cargo.lock`, and the
|
|
generated `CHANGELOG.md` entry. Review it like any other PR.
|
|
3. Merging that PR releases, but only once CI has passed on the merge commit — a published
|
|
crates.io version can be yanked but never withdrawn, so the `Wait for CI` job blocks the
|
|
publish until the CI run for that exact commit is green:
|
|
- tags `vX.Y.Z` and creates the GitHub release with the changelog as its notes,
|
|
- publishes `soulseek-rs-lib` then `soulseek-rs` to crates.io (dependency order, waiting
|
|
for the index between them),
|
|
- builds and attaches binaries with `.sha256` checksums for six targets:
|
|
|
|
| Archive | Notes |
|
|
| ------------------------------------------------ | ------------------------------ |
|
|
| `soulseek-rs-vX.Y.Z-x86_64-unknown-linux-musl.tar.gz` | static, any glibc |
|
|
| `soulseek-rs-vX.Y.Z-aarch64-unknown-linux-musl.tar.gz` | static, any glibc |
|
|
| `soulseek-rs-vX.Y.Z-x86_64-apple-darwin.tar.gz` | Intel Mac |
|
|
| `soulseek-rs-vX.Y.Z-aarch64-apple-darwin.tar.gz` | Apple Silicon |
|
|
| `soulseek-rs-vX.Y.Z-x86_64-pc-windows-msvc.zip` | |
|
|
| `soulseek-rs-vX.Y.Z-aarch64-pc-windows-msvc.zip` | |
|
|
|
|
- rewrites `Formula/soulseek-rs.rb` in the `michel/homebrew-tap` repository so
|
|
`brew install michel/tap/soulseek-rs` picks up the new macOS and Linux archives.
|
|
|
|
Both crates always share one version, one tag, and one changelog — see `release-plz.toml`.
|
|
|
|
## One-time repository setup
|
|
|
|
- **Settings → Actions → General → Workflow permissions**: enable *Allow GitHub Actions to
|
|
create and approve pull requests*. Without it the release PR is never opened.
|
|
- **Settings → Secrets and variables → Actions**: add `CARGO_REGISTRY_TOKEN`, a
|
|
[crates.io token](https://crates.io/settings/tokens) scoped to `publish-new` and
|
|
`publish-update`. Without it the tag and GitHub release still happen, but the crates.io
|
|
publish fails.
|
|
- **Homebrew tap**: create a public `michel/homebrew-tap` repository, then add a
|
|
`HOMEBREW_TAP_TOKEN` secret — a fine-grained PAT with *Contents: read and write* on that
|
|
repository only. `GITHUB_TOKEN` cannot reach another repository. The formula itself is
|
|
generated by the workflow; nothing in the tap needs editing by hand.
|
|
|
|
## Notes
|
|
|
|
- A merge with no releasable commits (only `docs:`/`chore:`/`test:`) opens no release PR.
|
|
That is intended.
|
|
- The release PR does not run CI on its own, because GitHub does not trigger workflows for
|
|
PRs opened with `GITHUB_TOKEN`. Pushing any commit to that branch yourself does start it —
|
|
handy if you want the version bump validated before merging.
|
|
- If one target's build fails, the other five still upload (`fail-fast: false`). To retry,
|
|
run the **Release** workflow manually and set `tag` to the existing tag (e.g. `v6.0.0`);
|
|
it rebuilds and re-uploads every target for that tag. Re-running the failed job from the
|
|
Actions UI replays the *old* workflow file, so it is no use when the workflow is the thing
|
|
that needs fixing.
|
|
- To skip a release for a commit that would otherwise trigger one, use a `chore:` type.
|
|
- **If CI flakes on the release commit the publish is blocked, by design.** The e2e suite
|
|
talks to a real soulfind server over the network and does occasionally time out. To
|
|
recover: re-run the failed CI job, wait for that run to go green, then re-run the
|
|
**Release** workflow. The gate reads the *newest* CI run for the commit, so it will then
|
|
pass. Never work around it by publishing by hand.
|
|
- Release binaries are stripped via `[profile.release] strip = true` in the workspace
|
|
`Cargo.toml`, so `cargo install` benefits too — not just the release archives.
|
|
|
|
## Installing a release
|
|
|
|
```bash
|
|
cargo install soulseek-rs
|
|
```
|
|
|
|
Or download an archive from the [releases page](https://github.com/michel/soulseek-rs/releases),
|
|
verify it against the adjacent `.sha256`, and extract the binary.
|
|
|
|
## Using the library
|
|
|
|
```toml
|
|
[dependencies]
|
|
soulseek-rs-lib = "6"
|
|
```
|