I came across conventionalcomments.org yesterday and love the idea. It is a simple convention for making clear comments on others' work products. In particular, code changes.
It is easy to unwittingly offend or confuse when commenting on someone else’s work, so I like that this gives a framework to set your intention early. Another nice side-effect is that it forces the commenter to think more clearly about what they’re actually trying to communicate.
I shared this with my dev team at work and plan to use it a lot more myself. I can see this being useful in pull requests as intended, but could also see it being useful when commenting on documents, slide decks, etc. I believe this would work well for feedback on any knowledge work product.
In case you don’t want to read the full web page I linked above, here’s a brief summary of the convention and ideas for different labels or tags you could use.
Format: <label> [tags]: <subject>
Example: suggestion (non-blocking): Consider using a framework for this
Labels (Prefixes):
- praise - Positive feedback
- nitpick - Trivial preference-based requests
- suggestion - Proposes improvements
- issue - Highlights specific problems
- todo - Small necessary changes
- question - Potential concern, needs clarification
- thought - Idea from reviewing (non-blocking)
- chore - Task that must be done before acceptance
- note - FYI info (non-blocking)
- typo - Misspelling
- polish - Quality improvements (like suggestion)
- quibble - Like nitpick
Decorations (Tags):
- (non-blocking) - Doesn’t prevent acceptance
- (blocking) - Prevents acceptance until resolved
- (if-minor) - Only resolve if changes are trivial