Desktop

Use this page as a copyable checklist when scaffolding or redressing a desktop app (native, Electron/Tauri, hybrid GUI+CLI). Parent class index: Delivery classes. Vocabulary: Auxiliary features.

Must-understand constraints

  • Windows — plan installer + update path on day one (MSI/MSIX/winget and/or in-app one-shot after quit). Prefer in-place setup EXE/MSIX; never unzip over a running folder. See Windows auto-updates.

  • macOS — App Store or notarized Sparkle-class / Homebrew cask; quit cleanly before replacing the .app bundle.

  • Linux — prefer distro/Flatpak/AppImage channels; do not overwrite a running ELF (see Unix/macOS auto-updates).

  • Prefer platform-native updates first; add in-app UX when channel speed or multi-track needs demand it.

Auxiliary feature matrix

Legend: A = 1.0 band · B = support/retention · C = fleets/scale · — = usually N/A

Feature Band Done means

Help menu / Help page

A

Discoverable Help: local HTML/CHM/adoc viewer or deep-link to versioned docs; includes shortcuts and “Report issue”

About dialog

A

Version + build id + channel + license; update status; link to dump — About

Check for updates

A

Manual check + optional background check; respects disable policy — Updates

Apply update safely

A

Stable feed URL; download+verify; quit process tree first; one-shot replace/installer (not a long-lived launcher); refresh shortcuts after exit; no self-replace on Store/winget/Homebrew; rollback when feasible

Debug dump / export logs

A

One click → redacted archive; never secrets by default

Open logs / config folder

A

Reveals paths for support; documented per OS

Preferences / Settings

A

Persisted settings; reset-to-defaults; paths for power users

Crash breadcrumb

A

Local crash file with build id; optional opt-in upload

Installer + uninstall

A

Signed package; ARP/Applications entry; clean uninstall — Distribution

What’s new

B

Post-update notes or changelog link from About/Help

First-run / onboarding

B

Short path to value; privacy choices up front

Single-instance

B

Second launch focuses existing window (or documented multi-instance)

Protocol / file handlers

B

Registered only if claimed; unregistered on uninstall

Tray / menu bar presence

B

If backgrounded: quit, About, Open, Update status; no silent forever-run without UI

Autostart

B

Opt-in; visible toggle; respects OS login-item norms

Offline / connectivity UI

B

Clear state when network/API required features fail

Report issue

B

Prefills version/build; points at issue tracker or email template

Keyboard shortcuts reference

B

Help → Shortcuts or searchable command palette help

Telemetry (opt-in)

C

Documented; off by default unless policy requires otherwise

Enterprise update pin/disable

C

Policy/env/managed config documented for IT

Proxy / custom CA notes

C

Documented for corp networks; doctor check when possible

Localization

C

UI strings externalized; locale follow OS or picker

Accessibility pass

B

Keyboard navigation; contrast; screen-reader labels on primary flows

Repair / reset

C

Reinstall-friendly; “clear cache” without wiping user documents

Help page (desktop specifics)

A desktop Help surface should answer:

  • What is this app and what is the current version?

  • Where are docs (offline copy preferred for air-gapped users)?

  • How do I update? How do I turn updates off?

  • Where are logs and how do I export a dump?

  • How do I report a bug?

Prefer versioned docs URLs (/docs/1.4/…) so old clients do not land on mismatched instructions.

Update behaviors by OS (summary)

OS Preferred apply pattern

Windows

Store/MSIX or winget upgrade for package-managed installs. Direct installs: stable feed → download+verify → quit first → one-shot in-place setup EXE/MSIX → refresh shortcuts → relaunch. Never unzip over a running folder or rewrite Start Menu .lnk while Explorer holds it.

macOS

App Store or Homebrew: deep-link native upgrade (no Sparkle self-replace). Direct: Sparkle-class quit → replace .app → relaunch.

Linux

Package manager / Flatpak (preferred); AppImage: stage beside → wait for PID exit → atomic rename → relaunch. Never write over a running ELF (ETXTBSY).

Channel stamp on About decides which path runs. Details: Automatic updates, Unix/macOS auto-updates, Windows auto-updates.

Suggested menu map

App / File
  Preferences…
  Quit
Edit …
View …
Help
  Documentation
  Keyboard Shortcuts
  Check for Updates…
  Report Issue…
  About <App>

macOS: About and Preferences under the application menu; Help contents under Help.

Related