New app checklist
Each group links to the page with the rules and the Editora code to copy. Everything here is a MUST unless it says SHOULD.
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, built to the edition its
README names. Click Use this template, run scripts/rename.sh <AppName> <package>, then add any rule on this list
from a later edition.
Platform
Section titled “Platform”- JDK 25 or newer (
release25 is the floor) and JavaFX 27 or newer - One JPMS module,
com.<app> - Maven Wrapper committed (
mvnw,mvnw.cmd,.mvn/wrapper/) - AtlantaFX light and dark themes, following the system by default
- Inter bundled and attached to every scene and dialog SHOULD
Code quality
Section titled “Code quality”- The version comes only from
pom.xml(filteredbuild-info.properties); lists that repeat a fact have a drift test - Rules live in pure, unit-tested helpers; UI classes stay thin
- A capture hook or headless screenshot drives the real window for UI checks
- Every package
@NullMarked; NullAway on Error Prone fails the build - Spotless with Palantir Java Format
- JUnit 5 and headless FX tests (
-Dglass.platform=Headless), FX tests taggedfx - JaCoCo check at 0.90 lines and 0.90 methods
Performance
Section titled “Performance”- No I/O, process, parsing or waiting on the JavaFX application thread; results return through
Platform.runLater - Background results applied under a generation guard; named daemon threads
- Redraws coalesced to one per pulse; streams delivered in batches
- Logs, histories and caches bounded; large inputs guarded
- Only the first frame built before it paints; update check and extras deferred
Keyboard and commands
Section titled “Keyboard and commands”- One
CommandRegistry: every action is a command with an id - Command Palette as an in-scene overlay, not a
Popup - Emacs and CUA keymaps at least, with user overrides on top
- One QuickOpen-style picker for every list choice (themes, keymaps, recent items, a setting’s values), in the overlay host SHOULD
- 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 and returns focus (
FindReplaceBar, Termina’sSearchBar)
Window shell
Section titled “Window shell”Window shell · Welcome page · Confirm dialog
- A Welcome page when there is nothing to restore, or an empty state that names the ways in with their chords SHOULD
- Every destructive action asks first through one helper: the question names the thing, the button names the action in the
dangerstyle, Escape cancels; or the action is undoable instead
Icons and color
Section titled “Icons and color”- Inter attached to every scene by a scene stylesheet; state colors named once on
.rootfrom the theme’s roles, no fixed hex in a component rule - Readable text in
-color-fg-mutedor stronger,-color-fg-emphasison an emphasis fill; a pure contrast test over the stylesheets SHOULD - Icons as themed SVG paths in one
Iconsclass, one style class per family, the same glyph for an action everywhere it is reached
Toolbars and tooltips
Section titled “Toolbars and tooltips”- Icon-only buttons built by one helper that sets the tooltip and the accessible name (
Icons.button,Icons.name) - Toolbar buttons out of the Tab order; every tooltip names the command and its chord from the active keymap
- Groups separated by spacing on one chrome band, no hairlines; a toggle wears
:openwhile it is on SHOULD
Tabs and panels
Section titled “Tabs and panels”- One tab header carries the states:
•and amber italic for unsaved, a pin and bold for pinned, muted italic for read-only (TabHeaders) - Bulk close skips pinned tabs, and Reopen Closed Tab brings the last one back with its caret (
ClosedTabs) - Panels toggled by commands, with side, order and divider positions restored on the next launch (
ToolWindowManager) SHOULD
- Menu rows are commands: icon, title and chord from the registry and the active keymap, no
KeyCombinationaccelerators - Every row of every menu, right-click menus and drop-downs included, has an icon that depicts it and its chord when bound, in the 11 px periwinkle column
- Menus draw in Inter 14 px whatever they were opened from (
.context-menupins the font in pixels) - Right-click menus close on a press anywhere outside them and never stack (
ContextMenuDismissalinstalled at startup) - Right-click menus open from the Menu key and Shift+F10 at the selected row (
RowContextMenu)
Tray and background
Section titled “Tray and background”Tray and background (for an app that keeps working without its window)
- The shared
tray/package: StatusNotifierItem on Linux, AWT elsewhere, created off the FX thread, and the app fully usable without one - Closing the window hides it only while an icon is up and the setting says so; Quit is explicit and one path
- Start at login writes the OS entry (XDG autostart, LaunchAgent,
HKCURun) with no setting beside it,--minimizedbehind the icon SHOULD - Desktop notifications through one
Notifier, off the FX thread, one switch per event
Settings
Section titled “Settings”- Settings window with a page sidebar, search and live apply
- A palette command for every setting
- Versioned config in
~/.<app>, with migrations and downgrade backups - Export and import of the config folder
- Config read with suspicion: values clamped on load, an unreadable file kept as a backup and defaults loaded
- No secret in a config file: keys and tokens in the OS keychain, a credential the app can ask for again in memory only
- 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
- Settings sync through a Git/GitHub repository SHOULD
Diagnostics
Section titled “Diagnostics”- Status-bar echo and Message Log
- Debug Log with a session file, and an uncaught exception handler
- Daily update check with an off switch; About shows versions, the Pauta edition and update status
- Report a Problem (redacted, prefilled GitHub issue) and
--report
Command line and languages
Section titled “Command line and languages”Command line · Internationalization
-
--help,--version,--config-dir,--dev - Single instance per config folder
- At least six message catalogs, with a parity test
Repository
Section titled “Repository”-
README.mdwith the badge row and a light/dark hero screenshot -
CHANGELOG.mdin Keep a Changelog format - MIT
LICENSE, andNOTICEwith every third-party license -
AGENTS.md, with a one-lineCLAUDE.mdpointing to it -
CONTRIBUTING.md,docs/andbranding/ -
.github/ISSUE_TEMPLATE/bug_report.yml
Documentation
Section titled “Documentation”- User docs on the app’s website under
/docs/: Getting started, a page per feature area, the keyboard reference, Settings and an FAQ - Help → Documentation as a command (
help.documentation), first in the Help menu after the Command Palette, and on the Welcome page - A one-line
command.<id>.descfor every command, held by the parity test -
docs/README.mdindexes the contributor guides;AGENTS.mdandCONTRIBUTING.mdpoint into it - Docs change in the same PR as the code; when they disagree with the code, the code wins and the docs are fixed
- Deep links from the app open the running version’s docs,
/docs/v-<version>/SHOULD - Command and keybinding references generated from the source, with a check that quoted ids and chords exist SHOULD
Packaging and signing
Section titled “Packaging and signing”Packaging, signing and release
- jpackage installers through JReleaser: Linux x64 and arm64, macOS arm64 and x64, Windows x64
- macOS
.dmgsigned with Developer ID, notarized and stapled - Linux downloads with
.ascsignatures from the shared release key - Build provenance attestations for every download
- Windows
.msiAuthenticode, once the certificate is chosen SHOULD - Homebrew cask in
adriandeleon/homebrew-tapand a winget packageAdrianDeLeon.<App>SHOULD
CI/CD (GitHub Actions)
Section titled “CI/CD (GitHub Actions)”-
ci.ymlon every push and pull request: Format and Build & Test, both required checks formaster -
full-tests.ymlon Linux, macOS and Windows: daily, on afull-cilabel, before every release SHOULD -
release.ymlon av*tag that matches the pom, with aworkflow_dispatchdry run - Every third-party action pinned to a commit SHA
- Dependabot for
github-actionsandmaven -
permissions: contents: readby default; write only in publishing jobs -
timeout-minuteson every job; superseded pull-request runs canceled - Test and coverage reports uploaded; coverage totals in the job summary
- Signing skipped without secrets, but a tag without them fails
- A smoke launch of the packaged app on each OS before release
Pauta 4.0.0 · · Changelog · This page in the latest edition