Your first auto-update is a promise. Your second one is where you find out whether you kept it.
We build DraftKey, a small Mac app for Tab autocomplete and reviewed rewrites. Between September 20 and November 11, 2026 we tagged 52 public releases on GitHub, from 0.1.1 to 0.1.62. That is a lot of updates to push at people who installed a writing tool and mostly want it to stay out of the way. This post is about the boring plumbing that made that pace survivable, and the one early bug that forced users to reinstall by hand.
Everything about DraftKey below comes from our public release notes. The general mechanics come from Apple's and the Sparkle project's public documentation, linked at the end. If you ship a Mac app outside the App Store, most of this applies to you whatever updater you use.
Release 0.1.1: decide what an update must never touch
The 0.1.1 notes are short, and every line is a rule we still follow:
- You can check for and install signed updates from the menu bar or from Settings, under About.
- Automatic update checks can be turned off.
- Installing an update requires your approval.
- Updates preserve your license, your preferences, and the downloaded writing model.
The last line matters more than it looks. DraftKey's download is about 1.12 GB and needs about 2.2 GB of free space, because it ships with a writing model. If an update quietly dropped that model, or reset the license, every release would feel like a reinstall. So before shipping a second version, write down the state that has to survive an update. For us it was three things: the license, the preferences, and the model. Then keep that state outside the app bundle, because the bundle is exactly what gets replaced.
Release 0.1.2: the updater bug you can't update your way out of
The very next release, the same day, says this:
Fix Check for Updates and automatic update checks failing to start. Verify signed updates before extracting them, as required for signed feeds.
And then the uncomfortable part:
If you installed 0.1.0 or 0.1.1, download this installer once and replace DraftKey in Applications.
That is the trap. When the updater itself is broken, the fix can't reach anyone through the updater. Everyone on the broken build has to come back to your website and reinstall manually, and most of them won't know they need to.
Two lessons came out of that.
Test the update path, not just the app. Before a release goes out, install the previous public build on a clean machine or user account and update it to the new one through the real feed. Launching the new build on its own tells you nothing about whether people can get to it.
Verify before you unpack. Sparkle's documentation describes the model most Mac updaters follow. You generate a key pair once with its generate_keys tool, which keeps the private key in your Keychain. You ship the public key inside the app, sign each update archive with sign_update, and the app refuses any archive whose signature doesn't match. The order matters. Check the signature first and only then extract, so a tampered or corrupted archive never gets unpacked into a temporary folder at all.
Signing and notarization are two different checks
People mix these up, so here is the short version from Apple's documentation.
- Code signing with a Developer ID says who built the app and that it hasn't changed since it was signed.
-
Notarization means you upload the signed build to Apple's notary service, which runs automated checks and returns a ticket. Apple requires the hardened runtime for notarized apps. You submit with
xcrun notarytool submitand attach the ticket to the disk image or app withxcrun stapler staple, so Gatekeeper can verify it even when the Mac is offline at first launch. - Update signing, like Sparkle's EdDSA signature, is separate again. It protects the update feed, not first launch.
You want all three. Our 0.1.56 and 0.1.57 notes both lead with the same sentence, "Freshly built, signed, and notarized installer," and both open the standard drag-to-Applications window. A boring, familiar first install is a feature.
Ask before installing, and let people turn it off
It is tempting to update silently. We went the other way on purpose. Checks can be disabled, and an install waits for your approval. For a tool that sits in your text fields all day, the update should never be the thing that interrupts a sentence.
Making updates visible also helped in ways we didn't plan for. Release 0.1.11 added an update check right inside onboarding, along with a persistent update status. Someone who downloads an older installer from a cached link gets told right away that a newer build exists, before they form an opinion from stale code.
Write release notes for the person, not the commit log
Look at almost any of the 52 notes and you will see the same shape: what changed for you, in plain words, and occasionally what you have to do. Release 0.1.33 says checks "resume after memory pressure clears." Release 0.1.60 says the Open DraftKey button on the website "now starts guided setup, the same as opening it from Applications." There is no "refactored the state machine" in there.
When the notes are readable, they can do two more jobs. They tell users when an update is worth installing, and later they give you an honest public record. This post leans on that record instead of memory.
A checklist if you ship Mac updates yourself
- List the state an update must preserve, and keep it outside the app bundle.
- Ship your update signing public key in the very first public build. Adding it later means one more manual reinstall for everyone.
- Verify the signature before extracting anything.
- Before every release, update the previous public build through the real feed.
- Sign with Developer ID, enable the hardened runtime, notarize, and staple the installer.
- Ask before installing, and let people turn automatic checks off.
- Treat an updater bug as a special incident: put the manual reinstall instructions in the release notes and on the download page.
If you want to see how this feels from the user side, DraftKey is at getdraftkey.com. It needs an Apple Silicon Mac on macOS 14 or later with 8 GB of RAM.
What broke the first time you shipped an updater? I'm especially curious whether anyone found a clean way to rescue users stuck on a build with a broken update check.
Sources
- DraftKey public release notes: https://github.com/auratechnologiesllc/DraftKey/releases
- Sparkle documentation: https://sparkle-project.org/documentation/
- Apple, Notarizing macOS software before distribution: https://developer.apple.com/documentation/security/notarizing-macos-software-before-distribution
- Apple, Hardened Runtime: https://developer.apple.com/documentation/security/hardened-runtime
Top comments (0)