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 that already ticks every MUST on this list: a small runnable app with its tests, CI and release workflows and every repository document. Click Use this template, then run scripts/rename.sh <AppName> <package>.

Platform

Platform baseline

• JDK 25 or newer (release 25 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

Code quality gates

• The version comes only from pom.xml (filtered build-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 tagged fx
• JaCoCo check at 0.90 lines and 0.90 methods

Performance

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

Keyboard first

• 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

Settings

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
• Settings sync through a Git/GitHub repository SHOULD

Diagnostics

Diagnostics and support

• 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 and update status
• Report a Problem (redacted, prefilled GitHub issue) and --report

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

Repository documents

• README.md with the badge row and a light/dark hero screenshot
• CHANGELOG.md in Keep a Changelog format
• MIT LICENSE, and NOTICE with every third-party licence
• AGENTS.md, with a one-line CLAUDE.md pointing to it
• CONTRIBUTING.md, docs/ and branding/
• .github/ISSUE_TEMPLATE/bug_report.yml

Packaging and signing

Packaging, signing and release

• jpackage installers through JReleaser: Linux x64 and arm64, macOS arm64 and x64, Windows x64
• macOS .dmg signed with Developer ID, notarized and stapled
• Linux downloads with .asc signatures from the shared release key
• Build provenance attestations for every download
• Windows .msi Authenticode, once the certificate is chosen SHOULD
• Homebrew cask in adriandeleon/homebrew-tap and a winget package AdrianDeLeon.<App> SHOULD

CI/CD (GitHub Actions)

CI/CD

• ci.yml on every push and pull request: Format and Build & Test, both required checks for master
• full-tests.yml on Linux, macOS and Windows: daily, on a full-ci label, before every release SHOULD
• release.yml on a v* tag that matches the pom, with a workflow_dispatch dry run
• Every third-party action pinned to a commit SHA
• Dependabot for github-actions and maven
• permissions: contents: read by default; write only in publishing jobs
• timeout-minutes on every job; superseded pull-request runs cancelled
• 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