Clavem

Update prompts and release notes: when to ask, what to say, how not to nag

Ask once per version, remember what you asked, show the notes before the button, and say plainly when a license cannot download the update. Release notes should say what changed for the person reading them, in plain text, in under a screen.

The prompt has a budget

An update prompt interrupts the person using your app. Each interruption spends goodwill, and the same prompt shown every day for a minor fix spends it fast. Treat the prompt as something with a budget: a fixed number of times per version, with a clear way to say not now.

Three rules cover most cases.

  1. Ask once per version. After you have shown a version, switch to a quiet badge or a menu item.
  2. Let them say no. Offer “Remind me later” and “Skip this version”, and honor both.
  3. Make the exception explicit. Only a security fix earns a prompt on every launch, and the notes should say that it is one.

A decision function

Keep the policy in one function you can test. This one takes the update the check found and the state your app stores, and returns what to do:

const DAY = 86400_000;
export function decide(update, state, now = Date.now()) {
  if (!update) return 'none';
  if (update.critical) return 'prompt-now';            // security fix: every launch until installed
  if (state.skipped === update.version) return 'none';
  if (state.snoozedUntil && state.snoozedUntil > now) return 'none';
  const last = state.lastPrompted;
  if (last && last.version === update.version && now - last.at < 7 * DAY) return 'badge-only';
  return last && last.version === update.version ? 'prompt-now' : 'prompt-once';
}

I ran it against eight situations:

Situation Result
No update found none
New version, user never told prompt-once
Told two days ago badge-only
Told nine days ago prompt-now
User chose Skip this version none
User skipped 3.3.0, and 3.3.1 arrives prompt-once
Snoozed until tomorrow none
Critical fix, user had skipped it prompt-now

Store three small values: the version the user skipped, the last version you prompted about and when, and the time a snooze ends. The critical flag has to come from somewhere. The releases endpoint has no such field, so put a marker in the release notes such as a first line that begins “Security:”, or keep a small list of critical versions in the app.

What to show

Show the version, the notes and the choices. Put the notes before the buttons, because the notes are the reason to click.

Element Content
Heading “Inkwell 3.2.1 is available. You have 3.2.0.”
Notes The release text, scrollable, in plain type
Primary button “Install and restart”, or “Download”
Secondary “Remind me tomorrow”
Tertiary “Skip this version”

Name the current version as well as the new one, because people check it. If the update needs a restart or changes the data format, say so above the button.

Release notes that say something

Clavem stores notes as optional plain text up to 20,000 characters, and the endpoint returns them in the notes field. A dialog is a small space, so write for a person who will read ten lines.

Weak notes: “Bug fixes and performance improvements.”

Better notes:

New
- Export to PDF keeps your page breaks.
Fixed
- Importing a file over 200 MB no longer crashes the app.
- The sidebar no longer jumps when you rename a folder.
Changed
- The default autosave interval is now 2 minutes. You can change it in Settings.

A few habits help.

  • Lead with the change a person can see. Internal refactors belong in a developer changelog.
  • Name the cause of a fix in words the user would use. “Crash on large imports”, not “null pointer in the file reader”.
  • Say what to do. If a setting moved, say where.
  • Keep a longer changelog on your site and link to it for anyone who wants more. The dialog is a summary.
  • Write the notes before you upload the build. A release created with no notes is easy to publish with an empty field.

Sparkle’s generate_appcast tool adds a notes file placed next to each archive, an .html file or, from Sparkle 2.9 on macOS 12, a basic Markdown .md file. Whatever your framework displays, keep the source text short and plain, so it works in every dialog.

When the license cannot download it

A request without a valid license key still learns that a version exists, but gets no notes and no download link. This is the case where your wording matters most.

What the check finds Show
Newer version and a download link The normal prompt
Newer version, no link, license expired “Version 3.3.0 is available. Renew your license to download it.” with a renewal link
Newer version, no link, no key entered “Enter your license key to download updates.”
Newer version, major release that needs a new purchase “Inkwell 4 is a paid upgrade.” with the price and a link

Say it once, plainly, and keep the app working on the version they own. A customer who sees “update required” with no explanation concludes the app is broken. See upgrade pricing for major versions for the pricing side.

Beta channels and staged rollouts

The releases endpoint returns the most recently published release of a product. If you publish 4.0.0-beta.2 to your main product, it becomes the latest for everyone who checks. That is not what most customers want.

The clean answer in Clavem is a separate product for the beta channel. It has its own product id, its own releases and its own download links. Beta testers use the beta product id in the update check, and release builds use the main one. Giving testers a license for the beta product is the extra step to remember.

The same endpoint answers everyone alike, so there is no built-in percentage rollout. If you want one, make the decision in the app: hash the license key or the instance id, and offer the update only when the hash falls inside the first part of the range, widening the range day by day. It adds a small amount of code, and it gives you a way to stop before the whole base has the update.

After the update

When the app starts on a new version, compare it with the version stored from last time. If it changed, show the notes again once, as a “What’s new” panel. People who updated through an installer, or let an auto-updater work in the background, never saw the dialog, and this is the only chance they get to read the notes.

Test the prompt like a feature

The prompt is code with state, so test it. Write checks for the table above, and add three more that people forget:

  • The server is down or slow. The app should start at once, show nothing and try again later. Block the update host in a test and confirm there is no dialog and no delay.
  • The state file is missing or corrupt. Treat it as empty. Worst case, a customer sees one prompt too many.
  • The clock is wrong. A snooze that ends “tomorrow” on a machine with a clock set to 2030 will never end. Cap a snooze at a fixed number of days from the last prompt.

Finally, watch the first week after a release. If many people skip a version, the notes did not persuade them, and that tells you more than any survey.

Doing this with Clavem

Clavem stores your notes and files with each release and serves them through the releases endpoint with signed download links. Everything above, the prompt policy, the stored state and the wording, lives in your app. The technical side of the request is in checking for updates in a desktop app, and the field list is in the releases documentation.

Questions

What format are Clavem release notes?

Plain text, optional, up to 20,000 characters per release. The releases endpoint returns them as a string in the notes field, so design your dialog to show text, and do not depend on Markdown or HTML being rendered.

How do I run a beta channel without sending betas to everyone?

Use a separate product for the beta channel. The latest release of a product is the most recently published one, so a beta published to your main product becomes the latest for every customer.

Can I roll out an update to a percentage of users first?

Not with the releases endpoint, which answers every request with the same latest release. A staged rollout needs logic in your own update server or in the app.

Sources

  1. Sparkle documentation, release notes with generate_appcast (as of November 2026)