The documentation team reviews every new commit in a release to determine whether any documentation needs to be updated. The Jira Epic ref, GitHub Issue ref or Docs note in the commit message tells them why the commit was made to better inform their work on the documentation and release notes. This page provides guidance on when and how Cockroach Labs engineers should include these references or write these texts.

...

Why is including this information necessary?

A big part of the documentation team’s job is to review every commit made for a release to figure out if any documentation needs to be updated because of that commit. To do that, they need to understand why each commit was made.

When they know why a commit was made, they have the context needed to determine what in the documentation needs to be updated (if anything) because of the changeThe Documentation team uses “Release note” texts in commit messages to identify user-impacting changes in the product that might require documentation updates. However, those texts alone don’t help Docs writers understand why a change was made. This new information takes care of that, helping writers either connect the change to a high-level epic (e.g., on the product roadmap) or by simply adding additional context about why the change was made when there’s not a connection to an epic.

How do I include an Epic ref?

...