Commit Message Guidelines
Copyright 2014 by Assured Information Security, Inc. Created by Ross Philipson <[email protected]>. 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/.
DO NOT EDIT: This page has been migrated to Confluence: https://openxt.atlassian.net/wiki/display/DC/Commit+Message+Guidelines
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.
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 <[email protected]>
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.
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.