Merge "Adding git commit message best practices"
This commit is contained in:
commit
ed3bddb3e3
|
@ -97,3 +97,89 @@ You can use `Git Immersion <http://gitimmersion.com/lab_02.html>`_ to work
|
||||||
through tutorials for learning git.
|
through tutorials for learning git.
|
||||||
|
|
||||||
For reference, use the `Git Reference and Cheat Sheet <https://git-scm.com/doc>`_.
|
For reference, use the `Git Reference and Cheat Sheet <https://git-scm.com/doc>`_.
|
||||||
|
|
||||||
|
Commit Messages
|
||||||
|
===============
|
||||||
|
|
||||||
|
Commit messsages are the first things a reviewer sees and are used as
|
||||||
|
descriptions in the git log. They provide a description of the history of
|
||||||
|
changes in a repository. Commit messages cannot be modified once the patch is
|
||||||
|
merged.
|
||||||
|
|
||||||
|
Format:
|
||||||
|
|
||||||
|
- Summary Line
|
||||||
|
- Empty line
|
||||||
|
- Body
|
||||||
|
- Tags
|
||||||
|
|
||||||
|
Summary Line
|
||||||
|
------------
|
||||||
|
|
||||||
|
The summary line briefly describes the patch content. The character limit is 50
|
||||||
|
characters. The summary line should not end with a period. If the change is
|
||||||
|
not finished at the time of the commit, start the commit message with WIP.
|
||||||
|
|
||||||
|
Body
|
||||||
|
----
|
||||||
|
|
||||||
|
The body contains the explanation of the issue being solved and why it should
|
||||||
|
be fixed, the description of the solution, and additional optional information
|
||||||
|
on how it improves the code structure, or references to other relevant patches,
|
||||||
|
for example. The lines are limited to 72 characters. The body should contain
|
||||||
|
all the important information related to the problem, without assuming that the
|
||||||
|
reader understands the source of the problem or has access to external sites.
|
||||||
|
|
||||||
|
Tags
|
||||||
|
----
|
||||||
|
|
||||||
|
Tags are references used to link the change to other tools.
|
||||||
|
|
||||||
|
The following tags are required:
|
||||||
|
|
||||||
|
- The ``Change-id`` line is a unique hash describing the change,
|
||||||
|
which is generated automatically by a Git commit hook. This should not be
|
||||||
|
changed when rebasing a commit following review feedback, since it is used
|
||||||
|
by Gerrit, to track versions of a patch.
|
||||||
|
|
||||||
|
The following tags are optional; however, their use is recommended if they are
|
||||||
|
applicable to the patch:
|
||||||
|
|
||||||
|
- ``Closes-Bug``: #123456789: use ``Closes-Bug`` if the commit is intended to
|
||||||
|
fully fix and close the bug being referenced. Use the Launchpad ID of the bug
|
||||||
|
for the number; Gerrit automatically creates a link to the bug.
|
||||||
|
- ``Partial-Bug``: #123456789: use ``Partial-Bug`` if the commit is only a
|
||||||
|
partial fix and more work is needed. Use the Launchpad ID of the bug
|
||||||
|
for the number; Gerrit automatically creates a link to the bug.
|
||||||
|
- ``Related-Bug``: #12456789: use 'Related-Bug' if the commit is merely
|
||||||
|
related to the referenced bug. Use the Launchpad ID of the bug
|
||||||
|
for the number; Gerrit automatically creates a link to the bug.
|
||||||
|
- ``Partial-Implements``: Use this tag if the change partially implements
|
||||||
|
a Launchpad blueprint. Use the name of the blueprint as an ID.
|
||||||
|
- ``Implements``: Use this tag if the change fully implements
|
||||||
|
a Launchpad blueprint. Use the name of the blueprint as an ID.
|
||||||
|
- The ``DocImpact`` tag contains a comment about why
|
||||||
|
the change impacts documentation. Put DocImpact on a line by itself.
|
||||||
|
Use this tag to indicate that documentation is either contained in the
|
||||||
|
patch or has documentation impact.
|
||||||
|
When this tag is included in a commit
|
||||||
|
message, Gerrit creates a bug for the project affected by the change for task
|
||||||
|
tracking, or move to the openstack-api-site as needed.
|
||||||
|
- The ``APIImpact`` tag contains a comment about why
|
||||||
|
the change impacts a public HTTP API. Put APIImpact on a line by itself.
|
||||||
|
Use this tag to indicate that the patch impacts a public
|
||||||
|
HTTP API. When this tag is included in a commit message,
|
||||||
|
the API_Working_Group can use it to help find relevant reviews.
|
||||||
|
- The ``SecurityImpact`` tag is used to indicate that a change has
|
||||||
|
security implications and should be reviewed by the OpenStack Security Group.
|
||||||
|
- The ``UpgradeImpact`` tag contains a comment
|
||||||
|
about why the change impacts upgrades. It is used to indicate that a change
|
||||||
|
has upgrade implications for those doing continuous deployment or N to N+1
|
||||||
|
upgrades. Also consider updating the 'Upgrade Notes' section in the release
|
||||||
|
notes for the affected project.
|
||||||
|
- The ``Depends-On``: <gerrit-change-url> tag is used to refer to a change
|
||||||
|
the current one depends on. Use the permalink of the change.
|
||||||
|
- ``Task``: 1234: the number of the task in Storyboard implemented by the
|
||||||
|
change.
|
||||||
|
- ``Story``: 1234567: the number of the story in Storyboard to which the task
|
||||||
|
being implemented belongs.
|
||||||
|
|
Loading…
Reference in New Issue