Skip to content

Tighten and standardise operator-facing error messages #29

Description

@ausimian

Summary

Review Castle's operator-facing errors and warnings for directness, consistency, and useful recovery guidance. Keep the diagnostic detail an operator needs, but remove internal design explanations and repeated context.

This complements #15. That issue owns structured failures and command exit status; this issue owns the text shown to operators.

Problem

Several messages are substantially longer than the failure they describe:

  • lib/castle/commands.ex: the synthesised-record refusal, root-mismatch errors, unknown-release refusal, and restart-marker failures explain implementation history or multiple internal states before saying what the operator should do.
  • lib/castle/peer.ex: security and filesystem errors include long explanations that obscure the failed operation and recovery action.
  • lib/castle.ex: the missing-release-archive warning could lead with the missing archive and the action to take.

The ordinary operation errors are also inconsistent. Unpack, install, commit, and remove failures use different sentence shapes and punctuation, and file errors are not always rendered as human-readable filesystem errors.

Representative locations on release/1.0.0 include:

  • lib/castle/commands.ex:238, :263, :395, :518, :817, :1204-1277, :1442, and :1462
  • lib/castle/peer.ex:531, :829, and :1097
  • lib/castle.ex:125

Line numbers are pointers, not an exhaustive inventory.

Direction

  • State the failed condition first.
  • Follow with impact or recovery only when it helps the operator act.
  • Remove implementation history, defensive justification, and false contrasts.
  • Qualify ambiguous paths such as RELEASES with the relevant release directory.
  • Use a consistent shape for operation failures, such as Cannot <verb> <target>: <reason>.
  • Render filesystem reason atoms with :file.format_error/1; retain inspect/1 for structured OTP terms.
  • Preserve identifiers, paths, versions, and security-relevant facts needed to diagnose the failure.

Acceptance criteria

  • The identified Castle errors and warnings are shorter and use consistent terminology.
  • Restart-marker and release-root refusals explain the condition and next action without narrating Castle's internal design.
  • File failures use human-readable filesystem reasons where applicable.
  • Tests assert the revised messages where exact output is part of the contract.
  • Command results, exit status, and release-management behavior do not change as part of this issue.
  • RELEASE.md records the user-visible diagnostic cleanup.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions