Releasing
Releases are made from a maintainer's machine with just, the GitHub CLI (gh), makepkg, and an SSH key registered with your AUR account. Only the Homebrew bottle is built in CI.
While you work
Add a line to CHANGELOG.md under ## Unreleased for anything a user would notice, written for users: what changed and how to use it, not how it was built. Group entries under ### headings when there are several. That section becomes the release's GitHub Release notes, word for word.
just release-notes Unreleased shows what the next release will say.
Shipping a release
just ship 0.2.0ship stops at the first thing that isn't ready. It checks that:
- the version looks like
0.2.0and is newer than the last release tag, CHANGELOG.mdhas something under## Unreleased,- you're on an up-to-date, clean
main, and the tag doesn't exist yet, ghis signed in, and the AUR accepts your SSH key,- the Homebrew tap (
mah3uz/homebrew-tapon GitHub) exists, wrangleris logged in (npx wrangler loginindocs/), for the docs site.
Then it:
- Runs
just check(clippy and the tests). - Sets the version in
Cargo.toml,Cargo.lock, both PKGBUILDs, the Homebrew formula and the installation guide's download commands, moves## Unreleasedunder## 0.2.0 - <date>in the changelog, and commitsVersion 0.2.0. - Asks before going further. Answer anything but
yand nothing is pushed or published; undo the commit withgit reset --hard HEAD~1. - Tags
v0.2.0and pushesmainand the tag. - Runs
packaging/release.sh: buildsquarry-0.2.0-x86_64-unknown-linux-gnu.tar.gz(binary, README, licence) from the tag's sources intodist/, with a.sha256, and fills in both PKGBUILDs' checksums and.SRCINFOfiles and the formula's checksum. - Creates the GitHub Release
v0.2.0with the tarball, its checksum, and the changelog section as notes (just release-notes 0.2.0, with a compare link to the previous release). - Commits the checksums as
Release 0.2.0and pushes. - Publishes
quarry-sqlandquarry-sql-binto the AUR (just aur). - Publishes the formula to the Homebrew tap and waits for its bottle to be built (
just brew). - Builds the docs site and deploys it (
just docs-deploy), so what it says about installing and the new version goes live with the release.
If a step after the tag fails, ship says so; finish the remaining steps by hand, in order: just release, then gh release create … as packaging/release.sh prints, then commit and push, then just aur, then just brew, then just docs-deploy.
AUR packages
packaging/aur/ holds the two AUR packages. Both install the quarry command with shell completion, and conflict with the AUR's unrelated quarry package, which also ships /usr/bin/quarry.
| Package | Installs |
|---|---|
quarry-sql | Builds from the tag's source tarball, and runs the unit, CLI and driver tests |
quarry-sql-bin | The prebuilt tarball from the GitHub Release |
just aur publishes both through throwaway clones in dist/aur. It refuses when a checksum is missing, a .SRCINFO is stale, or the GitHub Release has no tarball yet. To try the source package locally, just package builds it from the committed HEAD into dist/, and just install installs it.
Homebrew formula
packaging/homebrew/quarry.rb builds quarry from the tag's source tarball with Cargo, on macOS and Linux, and installs shell completion. It's published to a tap, the GitHub repository mah3uz/homebrew-tap, which has to exist before the first release that uses it:
gh repo create mah3uz/homebrew-tap --publicThe tap's copy of the formula also has a bottle, a prebuilt binary for macOS 15 and later on Apple Silicon, so brew install there downloads quarry instead of building it. Intel Macs, older macOS and Linux still build from source. A bottle can only be built on macOS, so this is the one release step that runs in CI, on GitHub Actions in the tap.
just brew works through a throwaway clone in dist/tap. It keeps the tap's .github/workflows/quarry-bottle.yml the same as packaging/homebrew/bottle.yml, pushes the formula to a bottle/quarry-0.2.0 branch of the tap, and waits for the workflow that push starts. The workflow builds and tests the formula on macOS, uploads the bottle to the tap's quarry-0.2.0 release, writes the bottle do block into the formula, pushes that to the tap's main and deletes the branch. The tap's main never has a version without its bottle.
just brew refuses when the formula isn't at the current version or its checksum isn't the source tarball's, and fails if the workflow does; run it again once the cause is fixed.
Other recipes
| Recipe | Does |
|---|---|
just tarball | The release tarball from the working tree, for testing |
just release | Step 5 on its own, after a tag is pushed |
just srcinfo | Regenerate both .SRCINFO files after editing a PKGBUILD |