openstack/training-guides
Code Issues Proposed changes
training-guides/doc/upstream-training/17-commit-message.rst
Sylvain Bauza 112efc2cd2 Upstream Training proposal for modifications 
Design Summits are now held differently by using Etherpad for selecting
sessions. Also, drafts are no longer accepted by Gerrit because of various
bugs they were creating.

Change-Id: I642fac63a384846f085389e1e535ea2b5d02ef43
2014-10-06 21:11:55 +02:00

2.0 KiB
Raw Blame History

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

Bad: new feature and refactor

image

Good: new API + new feature

image

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

Exercise

Review each other’s commit messages on the draft