Skip to main content

Conventional Commits

DX does not require Conventional Commits for versioning and changelog generation, because we rely on Nx Release version plans instead.

That said, structured review feedback is still valuable. The guidance below is the content that used to be exposed in the sidebar through the autogenerated structure: it adopts the Conventional Comments format to make code review feedback easier to understand, search, and act on.

Why Use Structured Review Comments?​

  • Clarity: They provide a clear structure for comments, making it easier for others to understand your feedback
  • Consistency: using a standard format helps maintain consistency across different code reviews
  • Efficiency: they make it easier to search for specific types of comments, improving the efficiency of the review process

We encourage all contributors to adopt conventional comments in their code reviews to enhance communication and collaboration.
For more information, visit the Conventional Comments website.

Format​

Conventional comments use specific prefixes to indicate the type of feedback being given. Here is the generic format of a conventional comment:

<label> [decorations]: <subject>

[discussion]
  • label: indicates the type of feedback being given
  • subject: main content of the comment
  • decorations (optional): extra decorating labels for the comment, surrounded by parentheses and comma-separated (e.g. (ui, blocking))
  • discussion (optional): contains supporting statements, context, reasoning, and anything else to help communicate the “why” and “next steps” for resolving the comment

To see the full list of available labels, take a look at the Conventional Comments documentation.

Best Practices​

In addition to the Code Review Best Practices and the, consider the following best practices when using conventional comments:

  • leave actionable comments: make sure the author knows what to do next
  • use "could" instead of "should" (e.g. “You could consider using a map instead of a list” instead of “You should use a map instead of a list”)