Table of Contents Conventional comments cheatsheet Format label decorations

Source

Conventional Comments is a standard for formatting comments of any kind of review/feedback process

<label> (<decorations>): <subject>
[discussion]

The following are mandatory:

• label - A single label
• subject - Main message

The following are optional:

• decorations - Extra decorating labels for the comment, surrounded by parentheses and comma-separated
• discussion - Anything else (context, reasoning) to help communicate the “why” and “next steps” for resolving the comment.

Eg

issue (security, blocking): use framework to purify DOM

I'm concerned that we are again implementing our own DOM purifying function.
We already experienced serious security drawbacks in PR#XX.
Please use the framework `purifDOMElement` function instead.
 

Will involve action (ie involve blocking decorator)

• issue: user-facing problems - add suggestion
• chore: simple tasks that must be done because of common process (leave a link to it)
• nitpick: small but necessary changes

Make it better (use non-blocking or if-minor decorator):

• praise: no false praise, try at one per review
• suggestion: specific requests to improve, to be taken seriously
• question: a potential concern but not quite sure if it's relevant or not
• thought: an idea that popped up, non-blocking by nature, can lead to more focused initiatives and mentoring

List:

• non-blocking: should not prevent the subject under review from being accepted
• blocking: should prevent the subject under review from being accepted
• if-minor: gives some freedom to the author that they should resolve the comment only if the changes ends up being minor or trivial.