Commit and Comment Conventions

Some conventions around commit and comments for changes proposal or pull request.

Conventional Commits

A convention on top of commit messages, conforms with SemVer.

Why use conventional commits?

• communicate and document changes better (easier to read and track).
• a more structured commit history, helping others to contribute easier.
• directs us to commit by scope (a commit for a specific problem)
• helps to generate automatic changelog when using standard-version.

<type>[optional scope]: <description>

# example
feat(pages): add home page

If you are using VSCode, you can use this extension to help you compose conventional commit messages.

read more:

• Conventional Commits
• Standard Version

Conventional Comments

Code reviews can be better if we understand that the code we are reviewing are written by human and our review are also gonna be read by human. Sometimes we don’t realize if our comments are unhelpful. This can be improved by following Conventional Comments, a convention which are inspired by Conventional Commits and Google Engineering Practices.

example of unhelpful comments:

It’s not worded correctly

by giving a label prefix:

suggestion: It’s not worded correctly

how about other_word instead?

sounds better, right? Reducing undercommunication and misunderstandings.

<label> [decorations]: <subject>

[discussion]

read more: Conventional Comments