Skip to content
Pauta6.1.0

New app checklist

The rules of this edition, cut down to what a new app meets before its first release: every MUST, grouped by area, and the SHOULDs worth doing first. 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
  • A new app’s 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 helper, never stored, and a test holds the README to it · PAUTA-02
  • PautaConformanceTest checks pauta.json against the edition’s rules.json, and the README’s badge and line show the edition and the conformance · PAUTA-10, PAUTA-15
  • Where pauta.json has a checked list, each entry records a by-hand rule a person checked and found met, and none is stale; an app that records none meets the rule · PAUTA-18
  • AGENTS.md has a section on Pauta that names the edition and links its numbered llms.txt · PAUTA-17
  • About links the edition, Built to Pauta x.y.z or at Partial Working toward Pauta x.y.z, read from pauta.version, and shows the conformance with a link that opens the Pauta window · ABOUT-05, ABOUT-06, ABOUT-07, ABOUT-08, ABOUT-09
  • A Pauta window, help.pauta, in the palette and in the Help menu where the app has one, listing every exception with fixed links · 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 no enforcer rule refuses a newer JDK, in the main build or in a profile that turns itself on) and JavaFX 27 or newer · PLAT-01, PLAT-03
  • A jlinked runtime in every installer, so users never install Java SHOULD · PLAT-02
  • One named JPMS module · 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 or from tokens the app builds on them · PLAT-05, ICON-08

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 class answers which OS the app runs on, and no other class reads os.name · OS-02
  • A test runs as each OS and finds the same commands, menu rows and settings pages SHOULD · OS-03
  • Nothing behaves or is laid out differently by OS, except as the table “Where the OS’s way wins” says · OS-04

Code quality gates

  • Every package @NullMarked; NullAway on Error Prone fails the build · PLAT-09
  • Spotless with Palantir Java Format; CI fails an unformatted change in a Format job of its own · PLAT-10
  • JUnit 5 and headless FX tests (-Dglass.platform=Headless), every FX test class carrying one JUnit tag (Editora’s fx) · PLAT-11, QUAL-06
  • JaCoCo check at 0.90 lines and 0.90 methods, which no profile that activates by OS or by JDK version lowers or skips · PLAT-12
  • What decides whether a control is enabled or shown, or where a key or a click leads, lives in pure, unit-tested helpers; UI classes stay thin SHOULD · 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, but for the wait for the config read and the reading of the bundled resources the first window is built from (its fonts, the message catalog, the keymap, its icons) at start-up, and the last save as the app quits; 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; a stream the app shows delivered in batches; work only on what is visible and changed, with a virtualized control for a list the user or the data can grow without a limit the app sets · PERF-06, PERF-07, PERF-08
  • Text-driven work that leaves the FX thread or outlasts a frame waits for typing to pause; filtering an in-memory list is exempt · PERF-23
  • 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 command registry: every action is a command with an id, its title and one-line description from the message catalogs · KBD-01, KBD-03
  • One Command Palette in each main window, M-x in the Emacs keymap and Ctrl+Shift+P in the others or in an app’s one key table, an in-scene overlay, as every picker is (never 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, the Debug Log window included: searches as you type with a count, Enter and Shift+Enter step, Escape closes it and, over a terminal, never reaches the shell; an app whose main content is a list filters it instead, and so does a log shown as a list · 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), and in an app with a picker, the picker in the overlay host SHOULD · QOPEN-01, QOPEN-02

Accessibility

  • Every control reachable with Tab and operable with Space or Enter, except controls whose command the keyboard reaches another way; every button, toggle, menu button, link, combo box, check box, radio button and text field shows the focus ring when the keyboard focuses it · KBD-15, KBD-16
  • The focus ring 2 px wide at the default zoom, just outside the control, taking no room in the layout SHOULD · KBD-22
  • A find-bar or filter control out of the Tab order only where a command does its work, or a key the bar’s field handles does · FIND-16
  • Every control a person can reach has an accessible name, rows drawn from graphics included, held by a test · ACC-01
  • Custom controls state their role and state; canvas content is exposed to the screen reader SHOULD · ACC-02, ACC-03
  • Animations follow the OS’s reduced motion; color is never the only signal SHOULD · ACC-04, ACC-05

Window shell · Welcome page · Confirm dialog · About window

  • In an app with a menu bar: on Windows and Linux, the menu bar in the title bar (HeaderBar) by default, with a setting to fall back to a decorated window; on macOS, the system menu bar · WIN-03
  • 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, or can be taken back instead; where the app asks, the question names the thing, the button names the action in red, and Escape cancels · CONF-01, CONF-02, CONF-03, CONF-04
  • Every such question has one default button, never the red one: Cancel, or Save where saving is an option, so Enter destroys nothing · CONF-13
  • The buttons of every dialog with two or more buttons, a text prompt and a form included, are worded from the message catalog, never JavaFX’s stock OK, Yes, No, Cancel, Apply or Close · CONF-14
  • Dialog buttons in one order on every OS, Cancel to the left of every action · WIN-11
  • A UI zoom that scales the whole chrome, menus included, applied at once and kept across launches, with commands to zoom in, out and back · WIN-12
  • One quit method for every quit entry point the app has: the Quit row, the app.quit command and the system’s own Quit · WIN-13
  • A Quit in every app: the app.quit command and, where the app has a File menu or a main menu, a Quit row in that menu that runs the command · WIN-14
  • On macOS, Settings in the application menu, showing the active keymap’s chord SHOULD · WIN-15
  • About from the help.about command, the Help menu where the app has one (a menu bar’s, or a Help submenu of its main menu), and the macOS application menu: version and build, runtime, license, links to the home page, the source code and the releases, 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 theme setting that offers “follow the system”, 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 color in a component rule, whatever its spelling (a hex, rgba(), white) · 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; a contrast test holds each · ICON-10, ICON-11, ICON-12
  • Where the icons come in two families, each glyph in one family’s style class; 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 contrast test · ICON-09
  • The contrast tests pure: they read the stylesheets without starting the toolkit SHOULD · ICON-14

Toolbars and tooltips

  • Icon-only buttons built by one helper that sets the tooltip and the accessible name from one string, chord included (Icons.button, Icons.name) · TBAR-01
  • In an app with a toolbar, its buttons out of the Tab order; every tooltip names the command and its chord from the active keymap · TBAR-02, TBAR-03
  • Every tooltip shown after the same 400 ms delay SHOULD · TBAR-14
  • A toolbar never holds the only way to an action · TBAR-08
  • 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
  • The main toolbar: its icons overflow and its pinned tail never does, Settings last with Simple mode before it, buttons disabled while their command can’t act, a command hides the bar, and the bar keeps its height SHOULD · TBAR-15, TBAR-16, TBAR-17, TBAR-18, TBAR-19

Tabs and tool panels

  • In an app whose main window holds documents or sessions in tabs the user opens and closes: every tab operation is a command, on every tab of the strip, whatever it shows; a terminal app’s tabs have no close unmodified and no close all · 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); in a terminal, the running program as the title and a mark for a notification, bell or activity · 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 tool.<id> command shows and hides each tool panel, on M-1 to M-0 in the Emacs keymap, and a panel’s content is built on first use (ToolWindowManager) · TABS-13, PERF-14
  • Each panel’s place and size restored on the next launch SHOULD · TABS-15

Menus

  • In an app with a menu bar, its rows are commands: title, chord and any icon from the registry and the active keymap, no KeyCombination accelerators · MENU-01, MENU-02
  • Every row of every menu the app draws, right-click menus and drop-downs included, shows its chord when bound · MENU-15
  • The menus the app draws are in Inter 14 px at the default zoom whatever they were opened from, and follow the UI zoom (.context-menu sets the size from the zoom’s one value) · MENU-16
  • Menu rows 34 px high with a 22 px icon column, the chord at least 18 px after the title, on a card whose shadow’s offset is at least its radius SHOULD · MENU-18
  • In an app with a right-click menu: every row, tab, editor and read-only console, a log shown as text such as the Debug Log among them, has one with its own actions, each a command; a list that only navigates has none · 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, or for the focused view where it has no rows (RowContextMenu) · MENU-09

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

  • The tray is a StatusNotifierItem on Linux, with no AWT fallback, and AWT’s SystemTray on Windows and macOS, and the app is fully usable when no icon comes up, its status line saying why · TRAY-01, TRAY-02
  • Closing the window hides it only while an icon is up and the setting says so; the tray’s Quit runs the app’s one quit method and ends the program with the window hidden · TRAY-03, TRAY-04
  • Start at login writes the OS’s own entry (XDG autostart, LaunchAgent, HKCU Run), and --minimized comes up behind the icon, minimized when the tray setting is off, and shown when an icon was asked for and none came SHOULD · TRAY-05, TRAY-06

Notifications (for an app that sends desktop notifications, with a tray or without one)

  • Desktop notifications through one notifier, the text passed as data and never as part of a script and the call timed out after ten seconds or less, for what happened while the window was away, one switch per kind of event, most of them off at first · TRAY-09, TRAY-10

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, a setting that waits for a restart saying so on its row, and a palette command for every setting the Settings window shows · SET-04, SET-06
  • Config in ~/.<app> on Windows, macOS and Linux alike, unless a flag or, after it, the environment variable names another folder; 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
  • A config file written whole or not at all: to a temporary file beside it, then moved into place · SET-22
  • Export and import of the config folder · SET-12
  • A secret the user gave the app, where the app keeps it, never in a config file: in the OS keychain, or in memory for the session where no keychain answers; a credential the app does not keep held in memory only, never written · SET-13, SET-14
  • A secret in the wrong place refused (a sync URL with a password), and an option that weakens security only a config key · SET-15, SET-16
  • Settings Sync in an app with user data worth carrying between computers, 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 that posts an echo message · DIAG-02, DIAG-03, DIAG-04
  • Daily update check, started at least three seconds after the first frame, a status-bar notice of a newer version, Check for Updates and an off switch · DIAG-05, DIAG-09, DIAG-10
  • Report a Problem builds a report with the version, the OS, the runtime, a settings summary and the recent Debug Log · DIAG-06
  • A problem report redacted before it is shown: home paths, user names, e-mail addresses, credentials, tokens · DIAG-11
  • Report a Problem shows the report editable, copies it and opens a prefilled GitHub issue; nothing is uploaded · DIAG-12
  • A report too long for the issue link (7,500 characters) is pasted from the clipboard · DIAG-13

Command line · Internationalization

  • --help, --version, --config-dir, --dev and --report, which writes its file in the current folder · CLI-01, CLI-02, CLI-05
  • An unknown option stops the launch with a message and exit status 2; in an app that opens files named on its command line, - and what follows -- are files; a launcher’s own JVM options are skipped · CLI-12
  • -h for help, -v and -V for the version SHOULD · CLI-13
  • On Windows, a console launcher (or an attached console) so the flags print · CLI-11
  • Single instance per config folder · CLI-07
  • Six message catalogs, each with every key · INTL-01, INTL-08
  • The language chosen, else the system’s, else English; dates, numbers and the catalog’s messages keep the system’s region · INTL-14

Repository documents

  • README.md as a landing page of at most 250 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 short 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
  • Scripts in Java, run by the JDK as source files, or in sh or bash SHOULD · REPO-11

Documentation

  • User docs on the app’s website under /docs/: Getting started, a page per feature area, the keyboard reference, Settings and an FAQ, and no page in the app’s docs/ with a section that tells the app’s user how to install or use something · DOCS-01, DOCS-02
  • The help.documentation command opens the user docs, with a Documentation row where the app has a Help menu · DOCS-06
  • Release notes written for users, and in an app with a Welcome page, its What’s New opens this build’s release · DOCS-05
  • docs/README.md indexes the contributor guides · DOCS-12
  • Docs change with the code, the website’s in a pull request opened with it; when they disagree with the code, the code wins and the docs are fixed, as AGENTS.md and docs/README.md say · DOCS-16, DOCS-17
  • Where the app has a Help menu, its rows in the family’s order, Documentation first after the Command Palette, then the keyboard reference SHOULD · DOCS-07
  • Every link from the app into its user docs opens 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

  • The CI workflow on every push to the default branch and every pull request: a format check and the build with its tests, both required checks · REL-19
  • The release workflow on a version tag that matches the pom, with a workflow_dispatch dry run · REL-21
  • A release cut only from a commit whose tests passed: the release workflow runs them, or its preflight reads CI’s result · REL-30
  • Every third-party action pinned to a commit SHA, with its version in a comment · REL-22
  • Dependabot for github-actions and maven, weekly · REL-23
  • permissions: contents: read by default, or none at all; write only in the jobs that need it · REL-24
  • timeout-minutes on every job that runs steps · REL-26
  • A concurrency group on every pull-request workflow that cancels a superseded pull-request run, and never a run on the default branch · REL-31
  • 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
  • The tests on all three OSes, daily or on every pull request, and before every release · REL-20

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