Desktop app release notes: writing for the update dialog

Desktop apps occupy a strange, privileged position in update land. Web apps change under their users silently. Mobile apps update overnight while the store page’s “What’s New” goes unread. Browser extensions install themselves without so much as a notification. But a desktop app — a Mac app with Sparkle, an Electron app with its updater, a Windows tool with an installer — still asks. A window appears: “Version 2.4 is available. Would you like to update?” And right there, sharing the window with the Install button, sit your release notes. This guide is about writing for that moment: the most-read changelog surface you will ever own, shown to a reader who is mid-task and deciding whether you’re worth a restart.

The most-read changelog surface you own

Think about who is looking at an update dialog. They didn’t go looking for your changelog — it interrupted them. They were in the middle of something, your app popped a window, and now they have a decision with a real cost attached: updating usually means a restart, lost window state, a broken train of thought. Your release notes are the sales pitch for paying that cost now rather than clicking “Remind me later” for the fourth time.

That framing changes how you write:

  • The first line carries the whole decision. Lead with the single best reason to restart: the bug that’s been biting them, the feature they asked for, the security fix. Everything else is supporting material.
  • “Bug fixes and improvements” is a request to be ignored. In a store listing it’s lazy; in a consent dialog it’s self-defeating. You are asking someone to interrupt their work for reasons you can’t be bothered to name. They will learn to click “Later” — and then your genuinely urgent update inherits that reflex.
  • Urgency is a budget. Spend it on security fixes and data-loss bugs (“We recommend updating now”), and spend it honestly — see how to announce a security fix. An updater that cries urgency every release trains users to ignore the one that matters.

Where the notes actually live

Every desktop update stack has a different answer to “where do release notes come from?”, and half the job is knowing yours.

  • Sparkle (macOS). The classic. Your app polls an appcast — which is literally an RSS feed — and each version’s item carries release notes either embedded as HTML or via a releaseNotesLink pointing at a hosted HTML page, rendered right inside the update dialog. A clean, per-version web page is the dialog content. Sparkle even stacks notes for skipped versions, so a user jumping 1.4 → 1.9 sees the whole span.
  • electron-updater / electron-builder. The updater surfaces releaseNotes from your update metadata (commonly the GitHub Release body). But the stock UX is minimal — many Electron apps build their own “What’s new” window and fetch notes themselves, which means the content pipeline is entirely yours to design. A JSON feed of your changelog is the natural source.
  • Squirrel (Mac and Windows). Famously updates silently and shows nothing by default. If your app uses Squirrel and you want users to see notes at all, you build the surface yourself — same answer: fetch your changelog’s feed, render it in-app.
  • Windows package managers and installers. winget and MSIX give you no real notes surface at decision time; classic NSIS/MSI direct downloads have no update UI at all until you add one. For all of these, the notes live on your website — linked from the download page and from whatever update-available toast you show.
  • Store builds. If you also ship through the Mac App Store or Microsoft Store, that channel has its own “What’s New” field with its own rules — covered in app store release notes.

Notice the pattern: every stack either renders a hosted page, fetches a feed, or leaves you to do it yourself. The architecture that serves all of them is the two-layer one: a canonical hosted changelog — dated entries, stable permalinks, RSS and JSON feeds — and thin per-channel slices (appcast items, release bodies, store fields) that point back at it.

Write for the version-skipper

Desktop users skip versions constantly — the laptop was closed for two weeks, the dialog got “Later”-ed five times, the office machine updates quarterly. When they finally update, they cross several releases at once. Two consequences:

  • Every entry must stand alone. “Fixed the regression from 2.3” means nothing to someone coming from 2.1. Name the symptom: “Fixed: search results no longer disappear when you switch projects.”
  • The dialog should show the span, not just the tip. Sparkle does this automatically from the appcast; if you built your own window, fetch every entry since the installed version (a changelog API with a since filter, or just render the latest N). A user who jumps five versions and sees only one release’s notes concludes — wrongly — that nothing else happened.

Two courtesy lines that cost nothing and buy goodwill: whether a restart is required, and anything that will look different immediately after relaunch (“the sidebar moved”). Users forgive change; they resent surprise.

No review clock — use the luxury well

Direct-distributed desktop software has something almost no other platform grants: you ship the moment you decide to. No store review, no rollout lag you don’t control. That makes the timing rule simple — write the entry at tag time, publish it the moment the update is live. The entry and the appcast item should appear together; a user who gets the dialog before the notes page exists sees a broken link inside your own product.

If you use staged rollouts (Sparkle’s phased rollout interval, electron-updater’s staging percentage), publish the notes at first availability and date them the same — the changelog documents when the release started reaching people, and early users are exactly the ones who’ll go looking. A scheduled-publish feature (or a draft flipped live from your release script) makes the timing mechanical instead of a thing you remember at 11pm.

And when a release goes wrong, the same no-clock luxury applies: you can ship a fix in hours — pair it with an honest entry per the hotfix communication playbook rather than a silent re-release with the same version number (which breaks updaters and trust in one move).

After the restart: the in-app “What’s new” moment

The update dialog is pre-restart; there’s a second, calmer moment right after relaunch. Etiquette mirrors the what’s-new widget rules: for a routine release, a small badge or menu item (“What’s New in 2.4”) is plenty — never a modal for a bug-fix release. Save the one-time full-window treatment for a genuinely major version, show it once, and gate it on the version delta so reinstalls don’t re-trigger it. If the update changed anything the user will trip over — moved UI, changed shortcut, new default — that’s the moment to say so, with a link to the full entry.

An entry template for desktop releases

## 2.4.0 — <date>

The one-line reason to update (the fix or feature most users are waiting for).

**New**
- Feature, described by what you can now do.

**Fixed**
- Symptom, as the user experienced it — not the internal cause.

**Known issues**
- Anything you already know about, so support threads start informed.

Restart required. The sidebar layout has changed — details in the full notes: <permalink>

Keep the reason-to-update line first — in Sparkle’s dialog and most custom windows, only the first screenful is read before the button gets clicked.

Anti-patterns that teach users to click “Later”

  • “Bug fixes and improvements” in a consent dialog. The highest-attention surface in desktop software, spent on nothing. Every vague release makes the next dialog easier to dismiss.
  • Force-restart without notes. Taking the decision away and declining to explain it is how you end up in one-star-review territory. If you must force an update (critical security), the notes should be the best you’ve ever written.
  • Notes trapped inside the app. If the only place release notes exist is the update dialog, then support can’t link to them, prospective users can’t see momentum, and search engines can’t find them. The dialog should render a page that also exists on the web with a stable URL.
  • The appcast commit dump. Sparkle renders whatever HTML you give it. A raw git log or an unstyled wall of text, rendered inside your beautifully designed app, reads as neglect exactly where users are being asked to trust you.
  • Channel drift. The direct build’s notes say one thing, the Mac App Store field says another, winget says nothing. One canonical entry, sliced per channel — never rewritten per channel.
  • Silent workflow breakage. Changed a keyboard shortcut, moved a menu item, dropped a plugin API — without an entry. Desktop users build muscle memory and automation on your app; breaking either without a written word is how loyal users become ex-users. See announcing breaking changes.

One canonical changelog, rendered everywhere

Wakelog is built to be the canonical layer under all of this: post the entry from your release script with one curl (or wakelog post --from-git) at tag time, keep it as a draft until the build is live, and publish at release. Every entry gets a stable permalink — a clean, fast page that works as a Sparkle releaseNotesLink target — plus RSS and a JSON feed your custom “What’s new” window can fetch, an embeddable widget with theme=auto for in-app webviews, and tags (new / fix / security / announcement) so urgent releases look urgent. To be clear about the seams: Wakelog doesn’t generate your appcast or update metadata — your build tooling owns those — it’s the notes layer they point at. If you’ve been shipping a desktop app for years with no changelog at all, start from today — entry zero, no backfill guilt.

Start your free changelog   Next: in-app “What’s new” widgets →

Related guides

Last updated 2026-07-27 · All guides