RELEASING.md

🚢 Releasing

1. The workspace starts at 1.0.0. For later releases, run cargo xtask bump-version --patch (or --minor, --major, or an explicit version such as 1.1.0), then commit and push. cargo xtask version prints the current version.
2. Tag and push (git tag v1.0.0 && git push origin v1.0.0), or start the workflow by hand on any branch (Actions → Release BarSQL → Run workflow) with the version, and it tags the commit it runs on.
3. .github/workflows/release.yml checks that the tag matches Cargo.toml and isn't already on another commit, then builds for Linux (x86-64 and ARM64, in Ubuntu 22.04 containers), Windows and macOS while the full test suite runs on all three. Once both pass, it publishes every asset plus SHA256SUMS, each with a build provenance attestation that gh attestation verify <file> --repo Bare7a/BarSQL checks.

Run the workflow by hand with the version left empty to build the packages without publishing them; they stay on the run's page for 7 days.

cargo xtask package builds this OS's packages locally, into target/package/dist (on Linux, after cargo install cargo-deb cargo-generate-rpm). BARSQL_RELEASE_DIR=<that folder> cargo test -p barsql-app a_packaged_release_stages_its_app runs the updater over them.

Packages

Script	Portable updater asset (one top-level entry)	Other downloads
scripts/package-macos.sh	BarSQL-darwin-arm64.zip, BarSQL-darwin-amd64.zip (a BarSQL.app per architecture)	BarSQL-macos-universal.dmg
scripts/package-windows.sh	BarSQL-windows-amd64.zip (BarSQL.exe)	BarSQL.exe, BarSQL-amd64-installer.exe
scripts/package-linux.sh	BarSQL-linux-amd64.tar.gz, BarSQL-linux-arm64.tar.gz (BarSQL)	BarSQL-x86_64.AppImage, BarSQL-aarch64.AppImage, and on x86-64 BarSQL, BarSQL.deb, BarSQL.rpm
packaging/linux/PKGBUILD (release workflow, in an Arch Linux container)		BarSQL.pkg.tar.zst

• Only the portable updater assets name both a platform and an architecture, so portable copies never pick another download. The AppImage and the packages update from their own asset, and the installer and the dmg from the .zip.
• Release builds turn on the production feature, which enables the update check at launch. The release profile uses thin LTO and strips symbols.
• macOS: an .app for macOS 12 and later, signed with the Developer ID and notarized through the signing secrets, which a release requires. A fork or a build-only run without them signs it ad-hoc. Each zip holds its own architecture alone, half the size of a universal app, since the updater downloads the zip for the Mac's own chip, even from an Intel build running under Rosetta. The dmg holds a lipo universal app and an Applications link, so a copy installed from it keeps only its own architecture after its first update. BARSQL_NATIVE_ONLY=1 builds this Mac's architecture alone.
• Windows: crates/barsql/build.rs embeds the icon and the version block. Neither the .exe nor the installer is code-signed, so SmartScreen asks once before the first launch. packaging/windows/installer.nsi installs the app with the SQLite Database file class for .db, .sqlite, .sqlite3, .s3db and .sl3.
• Linux: cargo-deb and cargo-generate-rpm build the deb and rpm from crates/barsql/Cargo.toml, and makepkg builds the Arch package from packaging/linux/PKGBUILD. Each installs /usr/bin/BarSQL and a desktop entry that opens SQLite files; the deb and rpm work out their library dependencies from the binary. The window's app id is BarSQL, so Wayland docks match it to BarSQL.desktop. Both builds run in an ubuntu:22.04 container on GitHub's ubuntu-24.04 and ubuntu-24.04-arm runners, so the binaries need glibc 2.35 at most, which the build checks, and run on Ubuntu 22.04, Debian 12, Fedora 36, RHEL 10 and later. The ARM64 build makes only the tarball and the AppImage: every released version picks a .deb, .rpm or .pkg.tar.zst by its extension alone, so an ARM package would reach x86-64 copies too.
• Compression: the dmg is LZMA (ULMO, which macOS 10.15 and later open), the installer uses a 64 MB LZMA dictionary, the rpm an xz payload and the Arch package zstd --ultra -20. The deb keeps cargo-deb's xz and the AppImage appimagetool's zstd. The updater assets stay deflate .zip and gzip .tar.gz, the only formats released versions unpack.
• The icon's source is packaging/icon.svg. The macOS .icns sets it on Apple's icon grid (an 824px body on a 1024px canvas, with a shadow). Windows and Linux show the stack without its tile, since their taskbars and docks are mostly dark and the dark tile would disappear there, leaving the stack looking small. The title bar shows the stack too, in a dark and a light version (crates/barsql-ui/images/barsql-mark-*.svg). cargo xtask icons regenerates the set from it: the Linux PNGs, icon.ico, icons.icns and docs/icon.png, each size rendered from the vector, and the SVG copies for the app (the marks and its icon) and docs/.

macOS Signing and Notarization

With these repository secrets, the release workflow signs the apps and the dmg with the Developer ID and the hardened runtime, has Apple notarize them, and staples the tickets, so Gatekeeper opens BarSQL without asking. The README promises a notarized Mac app, so a release of Bare7a/BarSQL fails without them. A fork or a build-only run without them signs the apps ad-hoc and skips notarization.

Secret	Value
MACOS_CERTIFICATE	The Developer ID Application certificate with its private key, exported from Keychain Access as a .p12, in base64: base64 -i DeveloperID.p12 | pbcopy
MACOS_CERTIFICATE_PASSWORD	The password the .p12 was exported with
APPLE_API_KEY	The text of an App Store Connect API key's .p8 file: a team key with the Developer role, from Users and Access → Integrations → App Store Connect API
APPLE_API_KEY_ID	That key's Key ID
APPLE_API_ISSUER	The Issuer ID shown above the keys

• Only the account holder can create a Developer ID Application certificate: Xcode → Settings → Accounts → Manage Certificates → + → Developer ID Application.
• packaging/macos/BarSQL.entitlements turns off library validation, which the hardened runtime would otherwise use to refuse SQLite extensions signed by other developers or ad-hoc.
• packaging/macos/DeveloperIDG2CA.cer is Apple's Developer ID intermediate certificate, which a .p12 export leaves out and the workflow adds to its keychain. It expires in September 2031; replace it from apple.com/certificateauthority before then.
• To try the secrets without publishing, run the workflow by hand with the version left empty. Unzip BarSQL-darwin-arm64.zip from the run's dist-macos artifact: spctl -a -vv BarSQL.app should report source=Notarized Developer ID, and xcrun stapler validate should pass for the app and the dmg.
• Locally, BARSQL_MACOS_IDENTITY signs with a certificate in the login keychain, named as "Developer ID Application: …" or, when two share that name, by the SHA-1 hash security find-identity -v -p codesigning lists. BARSQL_NOTARY_KEY (the .p8 file's path), BARSQL_NOTARY_KEY_ID and BARSQL_NOTARY_ISSUER notarize too.

How Updates Work

Release builds check Bare7a/BarSQL's releases at launch and offer a newer one with a toast. About → Check for Updates does the same at any time. The code lives in crates/barsql-app/src/update* and crates/barsql-ui/src/update_dialog.rs.

1. Check. The latest release, if it is newer than this build. The asset depends on how this copy was installed: the .zip or .tar.gz named for this platform and architecture, or the .AppImage, .deb, .rpm or .pkg.tar.zst when the app came as one. Its digest comes from SHA256SUMS.
2. Install Update. The download goes to a fresh barsql-update-* folder in the temp directory, with progress. Its SHA-256 is checked, then the archive's single top-level entry is unpacked, guarded against zip-slip, links and oversized entries. An AppImage or a package stays as it is. An asset that SHA256SUMS does not list is refused. Closing the dialog leaves the download running, and Check for Updates reopens it where it got to. A folder left by an app that quit or crashed without applying its download is removed at a later launch, once that app is gone and nothing has touched the folder for an hour.
3. Restart & Apply. The app relaunches itself as a helper with the BARSQL_UPDATER_* variables set, then quits. The helper first marks the download's folder as in use, so a BarSQL started meanwhile leaves it alone. It waits for the app to exit, swaps BarSQL.app, the binary or the AppImage while keeping a backup until the new version has launched, restores the backup on failure, and logs to update.log in the data folder, starting it afresh each time.
   • When the folder isn't writable, like Program Files or /usr/local/bin, the swap runs as BarSQL --barsql-update-swap behind the system's admin prompt (UAC, the macOS password dialog or pkexec). On Windows it also updates the installer's version under Installed apps.
   • Windows can't delete the running BarSQL.exe, so the swap moves it aside as BarSQL.exe.old.<n>. The new version deletes that once the helper has exited, or, in a folder that needs admin rights, Windows deletes it at the next restart.
   • The Linux packages are installed with dpkg -i, rpm -U or pacman -U through pkexec instead.
   • If the prompt is cancelled or anything fails, the old version starts again.