github.com/wmuizelaar/kpt@v0.0.0-20221018115725-bd564717b2ed/docs/style-guides/errors.md (about)

     1  # kpt Error Messages Style Guide
     2  
     3  Validation error messages and documentation are an important part of the UX in
     4  kpt. In fact, validation error messages are most likely the first thing users
     5  experience. The general philosophy here is to have **precise**, **actionable**,
     6  and **consistent** error messages.
     7  
     8  ## Errors vs. Documentation
     9  
    10  In most cases, the error message should provide enough information to resolve
    11  the issue. Prefer short descriptions that explain what caused the specific error
    12  and what to do to fix it. More extensive explanations and general rules (if they
    13  take more than a sentence to describe) are for documentation (which is
    14  automatically linked in error messages).
    15  
    16  Generally, documentation should expand on what the error message says and help
    17  the reader understand how to prevent future mistakes.
    18  
    19  ## Error Message Rules
    20  
    21  In the table below, origin and scope of rules are denoted with a prefix
    22  
    23  - **K** is inherited from
    24    [Kubernetes conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#validation);
    25    rules with prefix
    26  - **R** are specific to Kpt.
    27  
    28  <!-- prettier-ignore -->
    29  |  Rule  | Description  | Examples  |
    30  | --- | --- | --- |
    31  | K1  | Where possible, tell users what they CAN instead of what they CANNOT do.  |   |
    32  | K2  | When asserting a requirement in the positive, use "must". Avoid words like "should" as they imply that the assertion is optional.  | a) "must be greater than 0"  b) "must match regex '[a-z]+'"  |
    33  | K3  | When asserting a formatting requirement in the negative, use "must not". Avoid words like "should not" as they imply that the assertion is optional.  | "must not contain '..'"  |
    34  | K5  | When referencing a user-provided string value, indicate the literal in quotes.  N Use quotes (%q format specifier in Go) around user-provided values. This includes file paths.  | "must not contain '..'"  |
    35  | K6  | When referencing a field name, indicate the name in back-quotes.  Where it's unclear from the message, reference the full field path.  | "must be greater than `spec.request.size`"  |
    36  | K7  | When specifying inequalities, use words rather than symbols. Do not use words like "larger than", "bigger than", "more than", "higher than", etc.  | a) "must be less than 256"  b) "must be greater than or equal to 0".   |
    37  | K8  | When specifying numeric ranges, use inclusive ranges when possible.  |   |
    38  | R1  | If wrapping a runtime error, such as the result of a failed API Server call, use %w formatting verb in fmt.Errorf()(err) to include the root cause error. Refer to [Go error enhancements in 1.13](https://blog.golang.org/go1.13-errors).  |   |