Skip to content

Clarify usage of shall vs must vs others

Vishal Tak requested to merge vtak/styleguide_update into master

What does this MR do and why?

As a followup to !131259 (comment 1558246780) , this MR intends to add clarification around when to use "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL".

Different people and cultures have varying degree of understanding how each term can be used. e.g. https://docs.gitlab.com/ee/development/code_review.html#getting-your-merge-request-reviewed-approved-and-merged mentions Otherwise, a merge request should be first reviewed by a reviewer in each category (for example: backend, database) the MR touches, as maintainers may not have the relevant domain knowledge. This also helps to spread the workload. My interpretation of the should over here was that it is really required rather than being a "recommendation" as was clarified in !131259 (comment 1552877415) .

MR acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Merge request reports