Skip to content

Latest commit

 

History

History
94 lines (71 loc) · 3.89 KB

0011-unified-communication-with-the-users.md

File metadata and controls

94 lines (71 loc) · 3.89 KB
Raw

Table of Contents generated with DocToc

11. Unified communication with the users

Date: 2022-04-27

Status

Accepted

Context

We communicate with the user via messages printed in get_console() And we should make sure we communicate the msssages in a consistent way so that the users would understand:

  • whether verification of a condition succeeded
  • whether a message is just informational that might be used to understand what's going on
  • whether there is some important warning to potentially act on
  • whether there is a definite error that the user should fix
  • instructions how to proceed

The messages should be:

  • short
  • informative
  • readable
  • actionable

Decision

We are using rich and colours to communicate the type of messages:

  • [success] - to show verification success (green)
  • [info] - to present inform users (bright_blue)
  • [warning] - to print warning that the user probably should read and act on (bright_yellow)
  • [error] - when there is an error that the user should fix (red)
  • instructions should be printed without style and default rich rendering should be used

By default, we map those styles to those colors, but we can change configuration of Breeze to be colour-blind-friendly by disabling colours in communication via breeze setup config --no-colour.

When signalling warning or error The communication should not be confusing and should not contain "noise". It should contain simple - usually one-liner - information on what's wrong or what the user is warned against, possibly followed by instructions telling the user what to do. When we are able to foresee that error will happen, we should print the message only with explanation, and we should suppress any stack-traces as they are not really useful for the users. When an error is unexpected, full stack trace should be written to allow easier investigation of the problem.

We should also support --verbose flag to display all the commands being executed, and the --dry-run flag to only display commands and not execute the commands. This will allow to diagnose any problems that the user might have.

Whenever we print a logically separated message we should add EOL to separate the logical part of the message as well as when you want to separate the header description from bullet lists (very similar to what .rst rules are for readability). Whitespace improves readability of communication and messages separated in sections separated by whitespace and marked with colors are much more readable than the wall of text without visible structure.

Consequences

Users will get consistent approach when it comes to context and expectations of their reaction for the messages. Developers will use consistent styles.