Commit Message Guidelines
- Ross Philipson
Copyright 2014 by Assured Information Security, Inc. Created by Ross Philipson <philipsonr@ainfosec.com>. This work is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/.
This is a set of guidelines for how to format commit messages for various types of commits to OpenXT. Because OpenXT uses the Github pull request mechanism, the standard patch submission via mailing lists guidelines don't really apply. There are mainly two types of commits that are addressed here. General commits are those where a pull request has one or more commits that will go directly into a repository. Patch commits are slightly different. It is still a direct commit to a repository (a patch queue in this case) but the committed item is actually a patch.
General Commits
For a given pull request with say a number of commits in it, each commit should have a comment block that looks like this:
Short description Long description, multiple lines. OXT-X, OXT-Y, etc Singed-off-by: Jon Q. Public <jon.public@somewhere.com>
The short description should be 80 characters or less (basically 1 line). The long description could be optional if the short description says it all but that is usually not the case. The OXT ticket numbers list the JIRA tickets associated with the commit. If there are none, then this list is empty. Finally there is the standard Signed-off-by line. In addition other standard tag lines like Acked-by, Tested-by etc could be present.
Patch Commits
For patch commits the community would like the actual patch to contain a patch header message. The format of that message should be consistent with the upstream project the patch is related to. If it is not related to any upstream project or the committer is unsure, use the format for general commits. Below are links to guidelines for some of the common upstream projects:
OpenEmbedded:
http://openembedded.org/wiki/Commit_Patch_Message_Guidelines
Linux Kernel:
https://www.kernel.org/doc/Documentation/SubmittingPatches
Xen:
http://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches
Qemu:
http://wiki.qemu.org/Contribute/SubmitAPatch
Here is an example of a patch with a header message included in the OpenEmbedded project:
Finally since these are actual commits to Github too, a general commit message would be needed that is outside of the committed patch itself. This commit message can either match the one in the patch or follow the general commit guidelines above and it should contain the OXT JIRA ticket numbers list.
Pull Requests
In general pull request messages are just a copy of the commit message though they can be edited. One practice that has developed that has worked well is to prefix pull requests for branches other than master with their name in capital letters. We would like to continue to use this practice since it makes things easier on the reviewers and committers. This can be done in the actual commit message or by editing the pull request message (pull requester's choice). This is an example:
STABLE-6: Short description Long description, multiple lines. OXT-X, OXT-Y, etc Singed-off-by: Jon Q. Public <jon.public@somewhere.com>