Skip to content
Pauta4.5.0

Diagnostics and support

Rules on this page 8
IDLevelRule
DIAG-01MUST
The Message Log is a session-only, bounded history of every echo-area message with HH:mm:ss times, newest first. Esc closes it; Clear empties it. A click on the echo area opens it (WIN-01); the Message Log template has the rest.
DIAG-02MUST
The Debug Log captures all java.util.logging records and uncaught exceptions in memory (bounded) and mirrors them to <app>-session.log in the config folder, keeping the previous one as <app>-session.prev.log so a crash is still visible next launch.
DIAG-03MUST
The Debug Log opens in a modeless window with Refresh, Copy, Clear, Export and Report a Problem.
DIAG-04MUST
An uncaught exception handler is installed at the start of main, before the toolkit starts, and routes to the Debug Log and an echo message. Never a stack trace dialog.
DIAG-05MUST
The update notification reads GitHub /releases/latest once per app session (not per window), at most once a day, a few seconds after the first frame. A newer version shows a status-bar notice and a line in About; “Check for Updates” runs it by hand; Settings has an off switch. It never downloads or installs by itself.
DIAG-06MUST
Help → Report a Problem builds a report (version, OS, runtime, settings summary, recent Debug Log), redacts it (home paths, user names, e-mail addresses, credentials, tokens), shows it editable, copies it to the clipboard and opens a prefilled GitHub issue from bug_report.yml. Over about 7,500 characters the link falls back to “paste from the clipboard”. Nothing is uploaded. The same report from the command line, for when the app cannot start, is CLI-05.
DIAG-07SHOULD
A Doctor page checks the environment (external tools, versions, permissions, paths), with a status per row and a fix or link for each failure.
DIAG-08SHOULD
An app with user documents snapshots unsaved work off the FX thread and offers it back after a crash.
  • DIAG-01 MUST The Message Log is a session-only, bounded history of every echo-area message with HH:mm:ss times, newest first. Esc closes it; Clear empties it. A click on the echo area opens it (WIN-01); the Message Log template has the rest.
  • DIAG-02 MUST The Debug Log captures all java.util.logging records and uncaught exceptions in memory (bounded) and mirrors them to <app>-session.log in the config folder, keeping the previous one as <app>-session.prev.log so a crash is still visible next launch.
  • DIAG-03 MUST The Debug Log opens in a modeless window with Refresh, Copy, Clear, Export and Report a Problem.
    • Why: it is the only way to see logs in a packaged build.
    • Check (by hand): open the Debug Log and keep working in the main window while it is open.
    • Reference: Editora ui/DebugLogWindow.java.
  • DIAG-04 MUST An uncaught exception handler is installed at the start of main, before the toolkit starts, and routes to the Debug Log and an echo message. Never a stack trace dialog.
    • Check (code): main calls the install method before any argument handling or launch, and the handler shows no dialog.
    • Reference: Editora DebugLog.install(). Editora, Torrenta and Termina log the exception but do not yet post an echo message.
  • DIAG-05 MUST The update notification reads GitHub /releases/latest once per app session (not per window), at most once a day, a few seconds after the first frame. A newer version shows a status-bar notice and a line in About; “Check for Updates” runs it by hand; Settings has an off switch. It never downloads or installs by itself.
  • DIAG-06 MUST Help → Report a Problem builds a report (version, OS, runtime, settings summary, recent Debug Log), redacts it (home paths, user names, e-mail addresses, credentials, tokens), shows it editable, copies it to the clipboard and opens a prefilled GitHub issue from bug_report.yml. Over about 7,500 characters the link falls back to “paste from the clipboard”. Nothing is uploaded. The same report from the command line, for when the app cannot start, is CLI-05.
  • DIAG-07 SHOULD A Doctor page checks the environment (external tools, versions, permissions, paths), with a status per row and a fix or link for each failure.
    • Check (by hand): open the Doctor with a tool missing and find its row failed, with what to install.
    • Reference: Editora doctor/*, ui/DoctorPane.java.
  • DIAG-08 SHOULD An app with user documents snapshots unsaved work off the FX thread and offers it back after a crash.
Editora's Message Log popup above the status bar
Clicking the status message opens the Message Log: this session's messages, newest first.
Editora's Report a Problem window
Report a Problem: a redacted, editable report that opens as a prefilled GitHub issue.
Editora's About window
About: version, runtime, license, links and the update status.
Editora's Doctor page
Doctor: each external tool with its version, or what to install.

Secrets never reach a log, a report or a config file: see Secrets stay out of files.

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