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
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
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
This commit is contained in:
@@ -0,0 +1,209 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user