Files
lintunes/docs/mac-release.md
T
trav f21c31940f
macOS / Tests (AppleSilicon) (push) Canceled after 0s
macOS / Tests (Intel) (push) Canceled after 0s
macOS / Build (AppleSilicon) (push) Canceled after 0s
macOS / Build (Intel) (push) Canceled after 0s
macOS / Publish the GitHub Release (push) Canceled after 0s
v0.97.0: macOS port (Round 129): OS-aware paths, config and cookies; Mac now-playing, packaging (PyInstaller .app, dmg build, signing notes, CI workflow) and docs
2026-11-17 22:41:48 -08:00

210 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Releasing the Mac app
Notes for trav. The repo still lives on the Gitea/Forgejo host
(`origin`). GitHub gets a **read-only push mirror** of it, and GitHub
Actions' macOS runners build the two `.dmg` files and attach them to a
GitHub Release. Nothing about the Linux workflow changes: Linux machines
keep updating with `git pull` from `origin`.
```
your push ──> origin (Gitea/Forgejo) ──push mirror──> GitHub
└─ tag vX.Y.Z → .github/workflows/mac.yml
→ Release vX.Y.Z: two .dmg + SHA256SUMS
```
## One-time setup
### 1. Public or private?
Make the GitHub repo **public**, for three reasons:
- **Downloads.** Mac users download from the Releases page. A private
repo's releases are invisible to anyone you haven't invited, and the
app's update check asks GitHub's API without logging in, so it can't see
them either.
- **Cost.** Standard GitHub-hosted runners are **free on public repos**. On
a private repo, GitHub Free includes **$12 a month** of Actions usage.
macOS runners cost **$0.062 a minute** (Linux is $0.006, so a Mac minute
costs about ten Linux minutes). $12 buys about **190 macOS minutes** a
month. One release runs tests and a build on two Macs, roughly 60–80
minutes in all, so a private repo covers two or three releases a month.
(Prices are from GitHub's billing docs, November 2026.)
- **License.** The .dmg bundles PyQt6, which is GPL-3.0, so LinTunes as
shipped is a GPL combination. Before the first public .dmg, add a
`LICENSE` file (GPL-3.0-or-later fits) to the repo. See
`packaging/mac/THIRD-PARTY.md`.
A private repo still works for trying the pipeline out. Builds then show
up as workflow artifacts, which only you can download.
### 2. Create the GitHub repo
Create an **empty** repository: no README, no license, no .gitignore. The
mirror's first push fills it. Its `owner/name` is what goes into
`GITHUB_REPO` in step 5.
### 3. A token for the mirror
On GitHub, go to Settings › Developer settings › **Fine-grained personal
access tokens** › Generate new token:
- **Repository access:** only the new repo.
- **Permissions:** **Contents: Read and write**, and **Workflows: Read
and write**. GitHub refuses any push that changes a file under
`.github/workflows/` from a token without the Workflows permission.
Metadata: Read is added for you.
- **Expiration:** as long as you're comfortable with. When the token
expires, the mirror stops, so put the date in your calendar.
(A classic token works too, with the `repo` and `workflow` scopes.)
### 4. The push mirror on Gitea/Forgejo
In the repo on the Gitea/Forgejo host, open **Settings › Repository ›
Mirror settings** and add a **push mirror**:
- **Git remote repository URL:** `https://github.com/<owner>/<name>.git`
- **Username:** your GitHub username. **Password:** the token.
- Tick **Sync when commits are pushed**, and leave a periodic interval as
well (say 8h) as a backstop.
- Click **Synchronize now** once, and check that the code shows up on
GitHub.
Two things to know about push mirrors:
- **The mirror force-pushes and prunes.** Anything that exists only on
GitHub is deleted on the next sync: commits, branches **and tags**. Never
edit, commit, tag or merge pull requests on GitHub. In particular,
never let GitHub create a tag (the "create a new tag on publish" box in
the Releases UI, or a workflow that tags). The next sync removes that
tag, and the release on it turns back into a draft. This is why tags
are made where the code lives (below).
- If the Gitea/Forgejo host runs Actions of its own, it may pick up
`.github/workflows/mac.yml` too, and those jobs then sit queued forever
waiting for a macOS runner. If that happens, turn Actions off for this
repo there (Settings › Repository › untick Actions).
### 5. Name the repo in the app
In `lintunes/release_info.py`, set:
```python
GITHUB_REPO = "<owner>/<name>"
```
While this is empty, the Mac app never checks for updates. Commit and
release as usual. Every Mac build made after that checks.
## Making a release
Releasing is **bump, commit, tag, push**. The tag is the only new step:
```sh
# __version__ in lintunes/__init__.py is already bumped and committed
v="v$(python3 setup.py --version 2>/dev/null | tail -1)"
git tag -a "$v" -m "LinTunes $v"
git push origin master --follow-tags
```
Run `git config push.followTags true` once, and a plain `git push` takes
annotated tags along from then on. That keeps the existing habit (each
round ends with a commit and a push), and the round's final step only
gains the `git tag -a`.
The mirror carries the tag to GitHub, and the tag starts **macOS**
(`.github/workflows/mac.yml`). The workflow:
1. runs the test suite on both kinds of Mac (reported, not blocking, until
the Linux-only tests are marked);
2. builds both apps with `packaging/mac/build.sh`. It refuses to build if
the tag and `__version__` disagree;
3. starts each app against a throwaway library (`smoke_test.sh`), and
checks the disk image mounts and verifies;
4. creates the GitHub Release `vX.Y.Z` with
`LinTunes-X.Y.Z-AppleSilicon.dmg`, `LinTunes-X.Y.Z-Intel.dmg` and
`SHA256SUMS`.
It takes around half an hour. Mac apps that are running see the new
release at their next check (a few hours at most) and show the `*`.
Not every version has to be a Mac release. An untagged version simply
never gets a .dmg. To rebuild a release (say, after a failed run), go to
**Actions › macOS › Run workflow** and pick the tag as the ref. The files
on the existing release are replaced.
A push to master that touches `packaging/mac/` or the workflow builds
without publishing, so packaging changes get tested. A plain push to
master doesn't build at all, which keeps macOS minutes for releases.
**Why not tag automatically when `__version__` changes?** A workflow on
GitHub could do that, but the tag would exist only on GitHub, and the next
mirror sync would delete it (see above). Tagging at the source is the only
version that survives the mirror.
## Turning on Developer ID signing (later)
Unsigned builds make every Mac user go through **Open Anyway** once. To
stop that:
1. Join the Apple Developer Program ($99 a year).
2. In Xcode or on developer.apple.com, create a **Developer ID
Application** certificate, and export it with its private key as a
`.p12` with a password.
3. Create an **app-specific password** for your Apple ID at
account.apple.com › Sign-In and Security.
4. On GitHub, add these under Settings › Secrets and variables › Actions:
| Secret | Value |
|---|---|
| `MACOS_CERTIFICATE` | `base64 -i DeveloperID.p12` (the whole output) |
| `MACOS_CERTIFICATE_PASSWORD` | the .p12's password |
| `MACOS_SIGNING_IDENTITY` | `Developer ID Application: Your Name (TEAMID)` |
| `MACOS_NOTARY_APPLE_ID` | your Apple ID email |
| `MACOS_NOTARY_TEAM_ID` | the 10-character team ID |
| `MACOS_NOTARY_PASSWORD` | the app-specific password |
The next tagged build signs every binary inside out, with the hardened
runtime and `packaging/mac/entitlements.plist`. It then signs the .dmg,
notarizes it with `notarytool`, and staples the ticket. Without the
secrets, `build.sh` says "Developer ID signing skipped" and signs ad hoc,
as it does today. Once a signed build is confirmed, take the "Open
Anyway" section out of `docs/mac.md`. Also try removing
`disable-library-validation` from the entitlements.
The signing path has never been run. Expect the first signed build to
need fixes.
## Building on a Mac by hand
On any Mac with Python 3.11 or later for that Mac's architecture, plus
Xcode's command line tools (`xcode-select --install`):
```sh
git clone <origin> lintunes && cd lintunes
PYTHON=python3.13 packaging/mac/build.sh
packaging/mac/smoke_test.sh build/mac/dist/LinTunes.app 20
open build/mac/LinTunes-*.dmg
```
Everything goes in `build/mac/`: the venv, the downloaded tools, the
app, and the .dmg with its `.sha256`. A Mac builds only for itself: an
Apple Silicon Mac makes the AppleSilicon dmg, and an Intel Mac makes the
Intel one.
## Updating what's bundled
- **ffmpeg / fpcalc**: `packaging/mac/tools.json` pins each download's URL
and SHA-256. To bump one, download the new file, run
`shasum -a 256` on it yourself, compare the result with the publisher's
checksum, then change the URL and hash together. Also update the
versions in `THIRD-PARTY.md`. The ffmpeg builds' publisher stops making
**Intel** release builds from January 2027. Keep the pinned 9.0.2 for
Intel until a replacement is chosen.
- **PyInstaller**: pinned at the top of `build.sh`.
- **Python**: `PYTHON_VERSION` in the workflow.
- **Minimum macOS**: `MINIMUM_MACOS` in `packaging/mac/plist.py`. It
follows PyQt6's macOS wheel tag (14.0 for PyQt6 6.12).
- **The icon**: `python3 scripts/make_icons.py --only mac` rewrites
`packaging/mac/LinTunes.icns` from `packaging/lint.jpg`. Commit the
result.