Skip to content

Latest commit

 

History

History
150 lines (114 loc) · 8.44 KB

release.md

File metadata and controls

150 lines (114 loc) · 8.44 KB

Release

How a build reaches a user. The local development loop is in development.md; the signing identity itself is in signing.md.

Packaging a DMG locally

./Scripts/build-dmg.sh            # -> build/Tinycast-<version>.dmg (version from project.yml)
./Scripts/build-dmg.sh 0.5.7      # -> build/Tinycast-0.5.7.dmg

It builds a Release Tinycast.app signed with Tinycast Self-Signed and packs it with an /Applications symlink. Official per-channel releases are built by CI, below.

Signing & Gatekeeper

Both local builds and CI releases sign with the same stable Tinycast Self-Signed identity, not an Apple Developer ID — so macOS quarantines a directly-downloaded DMG. The Homebrew cask strips that automatically; direct downloaders run xattr -dr com.apple.quarantine "…/Tinycast.app" once. Full details in signing.md.

How the in-app updater consumes a release

Every release publishes two assets from one build: Tinycast-<version>.dmg, which people download by hand and which the cask installs, and Tinycast-<version>.zip, which the in-app updater installs. The zip is produced with ditto -c -k --keepParent --sequesterRsrc — the only zip that leaves the code signature verifiable, which matters because the updater refuses any bundle whose signature does not prove it is ours.

A stable release publishes two more from the universal job, Tinycast-Universal-<version>.dmg and .zip, built from the same commit at the same version and bundle id but with both slices. They are uploaded after the thin pair, which keeps the thin zip first in the asset list so builds predating architecture-aware selection keep choosing it.

Three things a release must keep true, or the updater skips it:

  • It carries a .zip asset this Mac can run. A DMG-only release is not installable and is not offered, and an Intel build is offered nothing rather than a thin arm64 zip.
  • The tag parses as vMAJOR.MINOR.PATCH or vMAJOR.MINOR.PATCH-beta.N, and agrees with the prerelease flag. v0.9.7-sequoia deliberately parses as neither, which is what keeps beta installs off the macOS 15 build.
  • It is not a draft.

Both casks declare auto_updates true. That is Homebrew's flag for an app that manages its own version, and it is what keeps brew update && brew upgrade from fighting an app that updated itself: brew never reports Tinycast outdated, never re-downloads it, and never rolls a self-updated copy back. Removing that line would reintroduce exactly those three problems. See features/updates.md.

Continuous integration

.github/workflows/ci.yml runs on every PR, on a macos-26 runner with Xcode 26 (the same selection step as the release workflow). One job, a merge gate; a new push cancels the in-flight run for the same ref. Two steps, both of which shell out to a script rather than naming rules or harnesses in the workflow, so neither can drift:

  • the harnesses — ./Scripts/run-tests.sh.
  • lint — ./Scripts/lint.sh, with SWIFTLINT_REPORTER=github-actions-logging so every violation is annotated inline on the PR diff instead of being buried in the log. It runs under if: always(), so a failing harness still surfaces the lint annotations in the same run. Warnings annotate only; lint errors fail the job, exactly as a local run does.

It does not run on pushes to main. pull_request builds the merge result, so re-running after a merge would re-test content CI has already seen. A direct push to main therefore gets no run at all — use Actions → CI → Run workflow if one ever needs checking.

There is no xcodebuild step: a Debug build costs minutes on every run and the release workflow builds before it ships anyway, so CI keeps to the checks that finish in about a minute. The consequence is that a change compiling nowhere still turns the PR green — build locally before you open one. See testing.md.

Releasing

.github/workflows/release.yml builds and publishes a DMG from GitHub Actions, no local machine needed. Run it from the Actions tab (Release → Run workflow) and pick:

  • channel — beta or stable. Each builds a distinct app (Tinycast Beta.app / Tinycast.app) with its own bundle id, alongside the local Tinycast Dev.app. Beta gets an auto-incrementing -beta.N suffix (N = the Actions run number) so re-running never collides; stable ships the version as-is.
  • version — base semver, e.g. 0.2.0.

It builds on a macos-26 runner with Xcode 26 and publishes a GitHub Release tagged v<full-version> with a versioned DMG and zip asset, marked prerelease for beta. On success it also bumps the matching cask in the tap and announces the release on Discord.

A stable run then fans out to a second job, universal, which rebuilds the same commit with ARCHS="arm64 x86_64" and attaches Tinycast-Universal-<version>.dmg / .zip to the release the first job created, then bumps tinycast-universal. macOS 26 is the last release that boots on Intel, and those Macs need both slices. Both jobs pin ARCHS explicitly and assert the slices on every shipping binary — the app and the bundled ClipboardTextHelper: trusting ARCHS_STANDARD is what shipped a thin arm64 build to Intel users once already, and it also keeps the Apple silicon download from silently gaining a slice it never needs. A thin helper inside a universal app is the quiet form of the same bug: the app boots on Intel and only clipboard OCR stops working.

Release notes

Scripts/release-notes.sh composes the release body, and CI runs it just before gh release create. It is safe to run by hand against any tag — it only reads:

CHANNEL=beta TAG=v0.9.13-beta.61 ./Scripts/release-notes.sh /tmp/body.md /tmp/discord.md

The changelog itself comes from GitHub's own release-notes API, which lists every merged PR with its author and number — so contributors are credited without anyone maintaining a CHANGELOG.md, and without Conventional Commits. Nothing is ever committed to this repo: the tag is created server-side by gh release create, and no release, bot or version-bump commit exists.

Two details the script exists for:

  • The previous tag is picked per channel. Beta and stable tags interleave on main — the same commit can carry both — so "the previous release" is only ever right within one channel. A stable release therefore spans every beta since the last stable.
  • The body is split by <!-- tinycast:install -->. Everything above it is the changelog; everything below is the Homebrew and quarantine text, which only a download page needs. The update window cuts at that marker — see features/updates.md. Full PR URLs are shortened to #304, which still autolinks on the web and fits a 460pt window.

The Discord announcement carries the same changelog, truncated to fit Discord's component limit, and pings @everyone.

Homebrew tap automation

Each job's final step rewrites the version + sha256 of its cask (tinycast, tinycast@beta or tinycast-universal) in the homebrew-tinycast tap and pushes. It needs a HOMEBREW_TAP_TOKEN repo secret — a fine-grained PAT with Contents: read/write on the tap repo. Without the secret the step logs a warning and skips; the release still publishes. The sed is anchored to ^ version / ^ sha256, so a cask's two-space indent on those lines is load-bearing.

The three macOS 26 / macOS 15 casks all install Tinycast.app under com.tinycast.app, so they conflicts_with one another and Homebrew routes each Mac by depends_on: tinycast requires arch: :arm64, tinycast-universal takes the Intel Macs, and tinycast-sequoia covers macOS 15.

Website

.github/workflows/website.yml builds website/ (Next.js static export + Tailwind, with Fumadocs for the docs section) and deploys it to GitHub Pages at https://abue-ammar.github.io/tinycast/ on every push to main that touches website/. Enable it once via Settings → Pages → Source = GitHub Actions.

cd website && npm install && npm run dev     # local preview

The workflow uploads website/out — a Next.js export lands there, not in dist/. public/.nojekyll must stay: GitHub Pages runs Jekyll, which ignores _-prefixed directories, so without it every asset under _next/ 404s. See website/README.md.