7da3955588
Syntax and formatting cleanup for Sphinx/Hieroglyph. Change-Id: I3961c9f263bf98be367acff6da0697eda8366903
94 lines
2.0 KiB
ReStructuredText
94 lines
2.0 KiB
ReStructuredText
===============
|
||
Commit messages
|
||
===============
|
||
|
||
.. rst-class:: colright
|
||
|
||
| <teacher name>
|
||
| <date>
|
||
|
||
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
|
||
=============================
|
||
|
||
.. image:: ./_assets/17-01-bad-two.png
|
||
|
||
Bad: new feature and refactor
|
||
==============================
|
||
|
||
.. image:: ./_assets/17-02-bad-new.png
|
||
|
||
Good: new API + new feature
|
||
============================
|
||
|
||
.. image:: ./_assets/17-03-good.png
|
||
|
||
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
|
||
============================
|
||
|
||
.. image:: ./_assets/17-04-commit-message.png
|
||
|
||
Exercise
|
||
========
|
||
|
||
Review each other’s commit messages on the draft
|