Skip to content
Pauta5.0.0

Diagnostics and support

Rules on this page 10
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 check reads GitHub /releases/latest once per app session (not per window), at most once a day, a few seconds after the first frame (PERF-15). It never downloads or installs anything by itself.
DIAG-09MUST
When the check finds a newer version, the status bar says so, naming the version and linking its release. About’s line for the last check is ABOUT-02.
DIAG-10MUST
Check for Updates runs the check by hand, as a command in the palette and the Help menu, and Settings has an off switch for the automatic check.
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 check reads GitHub /releases/latest once per app session (not per window), at most once a day, a few seconds after the first frame (PERF-15). It never downloads or installs anything by itself.
  • DIAG-09 MUST When the check finds a newer version, the status bar says so, naming the version and linking its release. About’s line for the last check is ABOUT-02.
    • Check (code): the update coordinator posts a status-bar message with the newer version and its release link.
    • Reference: Editora ui/UpdateCoordinator.java.
  • DIAG-10 MUST Check for Updates runs the check by hand, as a command in the palette and the Help menu, and Settings has an off switch for the automatic check.
  • 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 5.0.0 · · Changelog · This page in the latest edition