training-guides/doc/upstream-training/source/17-commit-message.rst

Commit messages

Commit messages

• quality of the OpenStack git history
• carrot by alerting people to the benefits
• anyone doing Gerrit code review can act as the stick
• review the commit message, not just the code
• Developers read mostly, write occasionally
• https://wiki.openstack.org/wiki/GitCommitMessages

Structural split of changes

• Small means quicker & easier
• Easier to revert
• Easier to bisect
• Easier to browse

Things to avoid

• Mixing whitespace changes with functional code changes.
• Mixing two unrelated functional changes.
• Sending large new features in a single giant commit.

Bad: two independent changes

Bad: new feature and refactor

Good: new API + new feature

Do not assume ...

• the reviewer understands what the original problem was.
• the reviewer has access to external web services/site.
• the code is self-evident/self-documenting.

Information in commit messages (1/2)

• Describe why a change is being made
• Read the commit message to see if it hints at improved code structure.
• Ensure sufficient information to decide whether to review.

Information in commit messages (2/2)

• Describe any limitations of the current code.
• Do not include patch set-specific comments.
• The first commit line is the most important.

Required external references

• Change-id
• Bug
• blueprint

Optional external references

• DocImpact
• SecurityImpact
• UpgradeImpact

GIT commit message structure

Exercise

Review each other’s commit messages on the draft