#18423 Policy for message structure New discussion created by kaos With an increasing number of messages that Pants may present to its users, it would be helpful if there was a common structure to them, a message structure policy if you will. Both informational as well as error messages could benefit from a pre determined structure designed to be clear concise and to the point. This also makes it easier for users to recognize the various parts of a message they have not seen before simply by being familiar with how they are structured. For the above, I'm opening this discussion so we can decide if/what we would want to achieve in this space, with the following proposal: To help make sure the policy is followed, and more importantly make it easier to adjust over time, we should have a common framework for constructing these messages. This will also save on development where less time needs to be spent on figuring out how to properly format messages. The "message format framework" would take as inputs (based on applicability) a subject, verb-sentence, context and "next steps"/help. Possible message structure could be:

<subject>: <verb-sentence>
  <context>

  <next-steps>

This opens up the message with what it is about, and why, followed by some additional context and ends with some possible corrective or possible further action to take. Example with some made up content:

src/proj/foo-bar/file:21: failed to process according to requested parameters
  The processing request for parameters `a`, `b` and `c` during step `frobnicator`.

  See `ref` for common issues during `frobnicator` processing.

pantsbuild/pants