Skip to content
Pauta4.4.0

New app checklist

Each group links to the page with the rules and the Editora code to copy, and each line names its rules. Every MUST of this edition is on a line; a line marked SHOULD holds only SHOULDs. A rule’s level is the one on its own page, and npm run check fails when a line here disagrees with it.

Start from the template. adl-desktop-app-template is a GitHub template repository: a small runnable app with its tests, CI and release workflows and every repository document, made toward the edition its README names; its Pauta window lists what is left. Click Use this template, run scripts/rename.sh <AppName> <package>, then add any rule on this list from a later edition.

Conformance · Pauta window · About window

  • The app implements one edition, named by pauta.version in pom.xml, and states its conformance: Complete, Core or Partial · PAUTA-01
  • The first release is at Core or Complete · PAUTA-03
  • Every MUST and SHOULD the app does not meet is an exception in pauta.json: not applicable, a deviation (SHOULDs only) with a decision record, or pending with an issue in the app’s own repository, each with a one-sentence reason · PAUTA-04, PAUTA-05, PAUTA-06, PAUTA-07, PAUTA-08, PAUTA-09
  • A template repository says so in its pauta.json and records the rules only an app made from it can meet as app-only · PAUTA-16
  • The conformance is computed from the exceptions by one tested helper, never stored · PAUTA-02
  • PautaConformanceTest checks pauta.json and the README against the edition’s rules.json · PAUTA-10, PAUTA-15
  • About links the edition, Built to Pauta 4.3.0, read from pauta.version, and shows the conformance · ABOUT-05, ABOUT-06, ABOUT-07, ABOUT-08, ABOUT-09
  • A Pauta window, help.pauta, in the palette, the Help menu and About’s link, listing every exception with fixed links · PAUTA-12, PWIN-01, PWIN-02, PWIN-03, PWIN-04
  • A Pauta conformance page in the user docs with the same list · PAUTA-13
  • That page generated from pauta.json SHOULD · PAUTA-14

Platform baseline

  • JDK 25 or newer (release 25 is the floor) and JavaFX 27 or newer, with a jlinked runtime in every installer · PLAT-01, PLAT-02, PLAT-03
  • One JPMS module, com.<app> · PLAT-04
  • Maven Wrapper committed (mvnw, mvnw.cmd, .mvn/wrapper/) · PLAT-08
  • AtlantaFX 3 controls, and app stylesheets that take their colors from its -color-* tokens · PLAT-05, PLAT-06

Same on every OS

  • Every command, setting and window on Windows, macOS and Linux, with the same defaults; one the OS can’t serve is disabled and says why · OS-01
  • One Os class reads os.name, and no other class does · OS-02
  • A test runs as each OS and finds the same commands, menu rows and settings pages SHOULD · OS-03

Code quality gates

  • Every package @NullMarked; NullAway on Error Prone fails the build · PLAT-09
  • Spotless with Palantir Java Format, checked in CI · PLAT-10
  • JUnit 5 and headless FX tests (-Dglass.platform=Headless), FX tests tagged fx · PLAT-11, QUAL-06
  • JaCoCo check at 0.90 lines and 0.90 methods · PLAT-12
  • Rules live in pure, unit-tested helpers; UI classes stay thin · QUAL-05
  • A capture hook or headless screenshot drives the real window for UI checks · QUAL-09

Performance

  • No I/O, process, parsing or waiting on the JavaFX application thread; results return through Platform.runLater · PERF-01, PERF-02
  • Background results applied under a generation guard; blocking work kept off the common pool · PERF-03, PERF-05
  • Redraws coalesced to one per pulse; streams delivered in batches; work only on what is visible and changed · PERF-06, PERF-07, PERF-08
  • Logs, histories and caches bounded; large inputs guarded; a closed window releases what it held · PERF-11, PERF-12, PERF-13
  • Only the first frame built before it paints; update check and extras deferred · PERF-14, PERF-15
  • Every thread named and a daemon SHOULD · PERF-04

Keyboard first · Command Palette · Find bar

  • One CommandRegistry: every action is a command with an id, its title and description from the message catalogs · KBD-01, KBD-03
  • One Command Palette per window, M-x or Ctrl+Shift+P, an in-scene overlay (not a Popup) that lists every command · KBD-05, KBD-07, PAL-01, PAL-02
  • Emacs and CUA keymaps at least, each .mac.json variant binding the same commands, with user overrides on top · KBD-09, KBD-21, KBD-11
  • A find bar in the scene wherever there is text to search: searches as you type with a count, Enter and Shift+Enter step, Escape closes it; a list app filters instead · FIND-01, FIND-02, FIND-03, FIND-06, FIND-07
  • One QuickOpen-style picker for every list choice (themes, keymaps, recent items, a setting’s values), in the overlay host SHOULD · QOPEN-01, QOPEN-02

Window shell · Welcome page · Confirm dialog · About window

  • A status bar whose echo area shows the last action’s feedback, errors in red and warnings in amber, and opens the Message Log on a click · WIN-01
  • Every destructive action asks first: the question names the thing, the button names the action in the danger style, Escape cancels; or the action can be taken back instead · CONF-01, CONF-02, CONF-03, CONF-04
  • Dialog buttons in one order on every OS, Cancel to the left of the action · WIN-11
  • About from Help, help.about and the macOS application menu: version and build, runtime, license, links and the last update check · ABOUT-01, ABOUT-02
  • A Welcome page when there is nothing to restore, or an empty state that names the ways in with their chords SHOULD · WELC-01, WELC-02

Icons and color

  • Inter’s four faces bundled, registered before any CSS, and attached by a scene stylesheet to every scene, dialogs and popups included · ICON-01, ICON-02
  • Light and dark themes switched at run time, a “follow the system” choice, and an unknown theme falling back to the default · ICON-15, ICON-16, ICON-17
  • State colors named once on .root from the theme’s roles, no fixed hex in a component rule · ICON-07, ICON-08
  • Tinted text at 4.5:1 on its fill and on both grounds; -color-fg-emphasis on an emphasis fill; one focus ring · ICON-10, ICON-11, ICON-12
  • Icons in one family’s style class each, the same glyph for an action everywhere it is reached, every glyph set credited in NOTICE · ICON-19, ICON-20, ICON-24
  • Readable text in -color-fg-muted or stronger, held by a pure contrast test over the stylesheets SHOULD · ICON-09, ICON-14

Toolbars and tooltips

  • Icon-only buttons built by one helper that sets the tooltip and the accessible name (Icons.button, Icons.name) · TBAR-01
  • Toolbar buttons out of the Tab order; every tooltip names the command and its chord from the active keymap · TBAR-02, TBAR-03
  • The toolbar never holds the only way to an action, and its right-click menu is one reused menu · TBAR-08, TBAR-10
  • Groups separated by spacing on one chrome band, no hairlines; a toggle wears :open while it is on SHOULD · TBAR-04, TBAR-06, TBAR-07

Tabs and tool panels

  • Every tab operation is a command · TABS-01
  • One tab header carries the title and the states: • and amber italic for unsaved, a pin and bold for pinned, muted italic for read-only (TabHeaders) · TABS-02, TABS-03
  • Bulk close skips pinned tabs, pinning moves a tab to the end of the pinned group, and Reopen Closed Tab brings the last one back (ClosedTabs) · TABS-04, TABS-05, TABS-06
  • A command toggles each panel, and a panel’s content is built on first use (ToolWindowManager) · TABS-13, TABS-14
  • Panel side, order and divider positions restored on the next launch SHOULD · TABS-15

Menus

  • Menu rows are commands: icon, title and chord from the registry and the active keymap, no KeyCombination accelerators · MENU-01, MENU-02
  • Every row of every menu, right-click menus and drop-downs included, has an icon that depicts it and its chord when bound · MENU-14, MENU-15
  • Menus draw in Inter 14 px whatever they were opened from (.context-menu pins the font in pixels) · MENU-16
  • Every row, tab and editor has a right-click menu with its own actions · MENU-05
  • One right-click menu at a time; a press anywhere outside closes it, and so does Escape, returning focus (ContextMenuDismissal) · MENU-06, MENU-07, MENU-08
  • Right-click menus open from the Menu key and Shift+F10 at the selected row (RowContextMenu) · MENU-09

Tray and background (for an app that keeps working without its window)

  • The shared tray/ package: StatusNotifierItem on Linux, AWT elsewhere, and the app fully usable without an icon · TRAY-01, TRAY-02
  • Closing the window hides it only while an icon is up and the setting says so; Quit is explicit and one path · TRAY-03, TRAY-04
  • Desktop notifications through one Notifier, for what happened while the window was away, one switch per event · TRAY-09, TRAY-10
  • Start at login writes the OS’s own entry (XDG autostart, LaunchAgent, HKCU Run), and --minimized comes up behind the icon SHOULD · TRAY-05, TRAY-06

Settings · Settings Sync

  • Settings window from a palette command (Ctrl+,), with a page sidebar and search · SET-01, SET-02, SET-03
  • Live apply with no Save button, and a palette command for every setting · SET-04, SET-06
  • Config in ~/.<app>, versioned with migrations, a file newer than the build backed up and defaults loaded · SET-07, SET-09, SET-10
  • Config read with suspicion: values clamped on load, an unreadable file kept as a backup and defaults loaded · SET-11
  • Export and import of the config folder · SET-12
  • No secret in a config file: keys and tokens in the OS keychain, a credential the app can ask for again in memory only · SET-13, SET-14
  • A secret in the wrong place refused (a sync URL with a password, an unredacted problem report), and an option that weakens security only a config key · SET-15, SET-16
  • Settings sync through a Git repository the user owns SHOULD · SYNC-01, SYNC-02

Diagnostics and support · Message Log

  • Message Log of the session’s echo-area messages · DIAG-01
  • Debug Log with a session file in its own window, and an uncaught exception handler installed at the start of main · DIAG-02, DIAG-03, DIAG-04
  • Daily update check with an off switch · DIAG-05
  • Report a Problem: a redacted, prefilled GitHub issue · DIAG-06

Command line · Internationalization

  • --help, --version, --config-dir, --dev and --report · CLI-01, CLI-02, CLI-05
  • Single instance per config folder · CLI-07
  • Six message catalogs, each with every key, held by a parity test · INTL-01, INTL-08

Repository documents

  • README.md as a landing page of about 200 lines, with the badge row and the hero screenshot · REPO-01
  • CHANGELOG.md in Keep a Changelog format · REPO-02
  • MIT LICENSE, and NOTICE with every third-party license · REPO-03, REPO-04
  • AGENTS.md, with a one-line CLAUDE.md pointing to it · REPO-05, DOCS-14
  • CONTRIBUTING.md, docs/ and branding/ · REPO-06, REPO-07, REPO-10
  • .github/ISSUE_TEMPLATE/bug_report.yml · REPO-09

Documentation

  • User docs on the app’s website under /docs/: Getting started, a page per feature area, the keyboard reference, Settings and an FAQ · DOCS-01, DOCS-02
  • Help → Documentation as a command (help.documentation) · DOCS-06
  • A one-line command.<id>.desc for every command, held by the parity test · DOCS-09
  • Release notes written for users, and the Welcome page’s What’s New opens this build’s release · DOCS-05
  • docs/README.md indexes the contributor guides · DOCS-12
  • Docs change in the same PR as the code; when they disagree with the code, the code wins and the docs are fixed · DOCS-16, DOCS-17
  • The Help menu in the family’s order, Documentation first after the Command Palette SHOULD · DOCS-07
  • Deep links from the app open the running version’s docs, /docs/v-<version>/ SHOULD · DOCS-03
  • Command and keybinding references generated from the source, with a check that quoted ids and chords exist SHOULD · DOCS-04

Packaging, signing and release

  • jpackage installers for Linux x64 and arm64, macOS arm64 and x64 and Windows x64; JReleaser creates the GitHub release with every download · REL-01, REL-03, REL-11
  • The version in pom.xml is the one source: a vX.Y.Z tag releases it · REL-05
  • macOS .dmg signed with Developer ID, notarized and stapled · REL-15
  • Linux downloads with .asc signatures from the shared release key · REL-16
  • Build provenance attestations for every download · REL-18
  • Windows .msi Authenticode, once the certificate is chosen SHOULD · REL-17
  • Homebrew cask in adriandeleon/homebrew-tap and a winget package AdrianDeLeon.<App> SHOULD · REL-12, REL-13

CI/CD

  • ci.yml on every push and pull request: Format and Build & Test, both required checks for master · REL-19
  • release.yml on a version tag that matches the pom, with a workflow_dispatch dry run · REL-21
  • Every third-party action pinned to a commit SHA · REL-22
  • Dependabot for github-actions and maven · REL-23
  • permissions: contents: read by default; write only in publishing jobs · REL-24
  • timeout-minutes on every job; superseded pull-request runs canceled · REL-26
  • Test and coverage reports uploaded; coverage totals in the job summary · REL-27
  • Signing skipped without secrets, but a tag without them fails · REL-28
  • A smoke launch of the packaged app on each OS before release · REL-29
  • full-tests.yml daily, on a full-ci label and before every release SHOULD · REL-20

Pauta 4.4.0 · · Changelog · This page in the latest edition