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 so they can figure out what needs to change in the documentationto 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.
| Table of Contents | ||||
|---|---|---|---|---|
|
When should I include an Epic ref, Issue ref or Docs note?
Every commit must include an Epic ref, an Issue ref or a Docs note.
How do I choose which one to include?
If the change in the commit is made as part of an epic choose one of:
...
Otherwise, when there is no issue for the commit
Docs note
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 change.
How do I include an Epic ref?
The rules for an epic reference are:
...
| Code Block |
|---|
Epic: CRDB-8035 |
How do I include an Issue ref?
The rules for an issue reference are:
...
| Code Block |
|---|
closes #16750 Fix: #64276 informs: #33316 See also #62585, #43784 |
How do I include a Docs note?
The rules for a Docs note are:
The first line must start with
[Dd]ocs note:It may span multiple lines
The Docs note text will be this line and every subsequent line until another section is reached (Release note: or Release justification:) or until the end of the commit description is reached.
The contents will describe why the commit was needed.
What information do I need to put in the Docs note?
TODO:
Note that the text does not end up in the documentation. It is used to inform the docs writers and it does not need to be short or concise like folks often do for release notes.
What are some examples of Docs notes?
Do I still need to add a release note to commit messages?
Yes. They serve different purposes. The release note field is specifically for updating the release notes published with a release. The epic ref / issue ref / docs note is for helping inform the documentation team figure out everything else that needs to be updated in the docs of what needs updating in the documentation more generally for a release.