20. Check for Updates and Version
This section describes how the packaged desktop app gets new versions. Development mode (
npm run dev) does not support online updates.
20.1 Automatic and Manual Checks
The app checks for stable releases roughly every 24 hours. After launch it waits at least 30 seconds, then adds up to 60 minutes of random delay so every start does not hit the network immediately; a wake from sleep catches up only once.
When a newer version exists and the main window is in the foreground and interactive, a system prompt appears:
| Option | Behavior |
|---|---|
| Update and restart | Starts downloading right away, then restarts once the update is ready and unsaved work is confirmed |
| Skip this version | Suppresses automatic prompts for that version only; nothing downloads or installs, and newer versions still prompt |
| Later | Prompts again for the same version after 24 hours; nothing downloads or installs |
The prompt's Later is not the same as Restart later after a download: the former has not downloaded anything, so quitting the app installs nothing.
Manual checks always work and ignore Skip: Help → Check for Updates.... A manual check can also surface clearly labelled Preview builds on the public channel, without turning that check into a standing preview subscription.
20.2 Dialog States
The window shows a single App version; the frontend, backend, and Electron shell update together.
| State (English UI) | Meaning |
|---|---|
| You're up to date | You are already on the latest version |
| Update available | A newer version exists; review the release notes and click Download now |
| Downloading update... | Downloading the complete verified app package. Closing the dialog does not interrupt it, but if it came from the Update and restart prompt, closing also cancels this automatic restart |
| Preparing update. | On macOS the download finished and the native updater is still preparing; the app stays usable |
| Update ready | Click Restart and update to apply, or Restart later |
| Update failed | Network, metadata, checksum, or signature verification failed; Retry or close and try again later |
Preview builds show a Preview badge and stability warning, and the button reads Download preview. When the release type cannot be verified, the download is disabled rather than treated as stable.
20.3 Unsaved Work Before Restart
After you choose to restart, the app checks every editable window, including the main window and compare views, for unsaved work:
- With nothing unsaved, it continues automatically.
- With unsaved work, it defaults to Return to app (Esc does the same). The download is kept; save and press Restart and update again.
- If the unsaved state cannot be read, it does not continue and returns to an operable downloaded view with a retry hint.
A running query does not block the prompt, but restarting interrupts the query and disconnects external agents.
20.4 Common Cases
- Network interruption: A failed download does not corrupt the currently installed version; once the network is fixed, just Check for Updates again.
- Restart later: Keep using the current version. The downloaded update installs when you truly quit the app; on Windows, closing the window does not count if the app is configured to stay in the background.
- Restart and update (Windows): The restart shows install progress only, then launches the new version automatically. An all-users installation may still show UAC, and unsigned builds may still show SmartScreen; these are Windows system prompts. First-time manual installs still use the full installer wizard.
- Restart and update (macOS): The system update flow is used, without an install percentage window. If the app runs directly from the DMG or from a read-only location, move it to Applications first or the update cannot complete.
- Updating from 0.3.3: The install mode is decided by the old version that starts the update. 0.3.3 still starts it silently, so the move to 0.3.4 is silent too; the progress page appears from 0.3.4 onward.
- Stopping automatic prompts: Choose Skip this version, or ignore the prompt so it returns after 24 hours. State lives in the user data directory and usually survives an over-install, but a reinstall is not guaranteed to clear it.
- Release notes: The updater shows bounded English plain-text bullets; the release page keeps the full English and Traditional Chinese notes.
- Still shows the old version after updating: Confirm that you clicked Restart and update and waited for the app to fully restart.
- Update unavailable: Download the current full installer from the product release page. Do not bypass checksum or signature warnings.
20.5 Release Baseline
Version 0.3.0 is the first release using the standard Electron whole-app updater. Older hot-update proof-of-concept builds cannot upgrade themselves to this baseline and should install the current package manually once.
For release operations, see the internal desktop release SOP.
Per-version feature lists are on /changelog, including the current 0.3.4 release.
For the packaged app, if the official documentation URL has been configured, some Help documentation links in the app open the corresponding public documentation page in the browser (when not configured, the built-in Docs are still used).