Software Product Essentials

Software Product Essentials is the checklist every shippable artifact should satisfy before you call it “done.” Domain features are not enough. Users and maintainers need identity, provenance, update path, install story, Help/support, and a way to dump state when something breaks.

This page is the framework. Deep dives live in sibling articles; delivery-class templates list auxiliary features for desktop, web, and mobile; artifact-type pages say what to drop, adapt, or emphasize.

Why this exists

Teams routinely ship apps that:

  • Have no About surface, so support cannot tell which build a user runs

  • Cannot self-update on Windows, so users stick on stale binaries for months

  • Are “zip and pray” with no installer, PATH, shortcuts, or uninstall

  • Have no CI artifact story—releases are laptop builds

  • Cannot produce a privacy-aware debug dump when the user files a bug

Those gaps are architectural, not polish. Treat them as first-class product surfaces.

When an agent (or human) scaffolds or extends an owned app, consult this guide and its deep dives and implement the applicable essentials—do not leave About, updates, packaging, and diagnostics as “later.”

Shared essentials (all shippable software)

Every artifact that leaves your machine should cover these concerns in a form that fits its type. Libraries express them differently than GUI apps; the concern still exists.

Essential What “good” looks like Deep dive

Identity and provenance

Name, version, channel, commit/build id, OS/arch, and license visible to humans and machines

About and build info

About / status surface

Discoverable place (dialog, --version, /health, README badge) that answers “what am I running?”

Same

Debug / support dump

One action or command that exports redacted env + config + recent logs for bug reports

Same + Diagnostics

Update path

Users can move to a newer build without hunting a zip on a random page—especially on Windows

Automatic updates

Distribution

Install, upgrade, and uninstall via the platform’s expected channel (MSI/winget, pkg, AppImage, crates.io, …)

Distribution and packaging

Build pipeline

Reproducible CI builds, signed artifacts where required, attached to a tagged release

Build pipeline

Config and data layout

Documented paths for config, cache, logs, and secrets; no secrets in the dump by default

Diagnostics

Crash and error story

Failures leave a breadcrumb (log, crashpad, exit code + stderr); user can recover or report

Same

Docs and changelog

README entry points; changelog with timeline + details; Diátaxis when docs grow

Core principles
Quick agent checklists (printable)

App essentials checklist · Auxiliary features checklist

Auxiliary features and delivery classes

Beyond the shared essentials table, every end-user shell should plan a deliberate set of auxiliary features (Help, What’s new, Preferences, connectivity, privacy, support path, …).

Delivery class templates (copy into the project plan):

  • Delivery classes overview

  • Desktop — Help/About, tray, autostart, OS-specific update apply (including quit/replace on Unix)

  • Web — build identity, deploy-as-update, PWA reload, status/privacy

  • Mobile — store updates, permissions, crash export, policy-required account deletion

Artifact type (library vs GUI vs CLI…) and delivery class (desktop vs web vs mobile) are orthogonal—a product may ship more than one shell.

Applicability matrix

Legend: R = required for a mature product · A = adapt (different UX) · O = optional / rare · — = N/A

Concern Lib GUI CLI TUI Game Service

About / version surface

A

R

R

R

R

A

Build id in UI or --version

A

R

R

R

R

R

Debug dump button / command

O

R

A

A

R

A

Auto-update

—

R

A

A

R

A

Installer / package

A

R

R

R

R

R

CI release pipeline

R

R

R

R

R

R

Crash reporting

O

A

O

O

R

A

Telemetry (opt-in)

O

A

O

O

A

A
Type notes

  • Libraries — versioning and registry publish are the About/update story

  • GUI apps — full About dialog, dump button, Windows update + installer

  • CLI — --version / --help; updates via package manager or self-update

  • TUI — same as CLI plus an in-app About/help pane

  • Games — launcher/store updates; crash dumps; content pipelines

  • Services — health endpoints, rolling deploy, structured logs

Recommended product shape

Shared pipeline feeding typed distribution surfaces
flowchart TB
  Dev[Develop] --> CI[CI build + test]
  CI --> Art[Versioned artifacts + SBOM]
  Art --> Rel[Tagged release]
  Rel --> Pkg[Package managers / installers]
  Rel --> Upd[Update feed / channel]
  Rel --> Reg[Language registries]
  Pkg --> User[Installed product]
  Upd --> User
  User --> About[About / version / dump]
  About --> Support[Bug report]

Principles that keep this sane:

  1. One version truth — build stamps the binary; About and --version and the updater all read the same metadata.

  2. Channel awareness — stable / beta / nightly (or equivalent) is part of identity, not a footnote.

  3. Redact by default — dumps never include tokens, passwords, or full secret stores unless the user explicitly opts in.

  4. Platform-native first — prefer winget/MSI, Homebrew, apt/dnf, Flatpak/AppImage over custom update UIs when they suffice; add in-app update when store latency or UX demands it.

  5. Windows is not optional — if you ship a desktop app to Windows users, plan MSI/MSIX or equivalent + an update story on day one.

Minimum bar by maturity

Stage Must have

Prototype

Semver or calver string; README; runnable from source

Internal dogfood

Build id; CI artifact; log file path; manual update instructions

Public beta

About surface; debug dump; signed installer or registry package; release tags; changelog

1.0

Auto-update or package-manager updates; uninstall; crash breadcrumbs; support path documented

How-to entry points

Related