Skip to content

Commit Message Guidelines

rossphilipson edited this page Nov 10, 2014 · 6 revisions

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 <[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.

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 you are 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:

http://cgit.openembedded.org/meta-openembedded/diff/meta-oe/recipes-support/libyaml/files/libyaml-CVE-2014-2525.patch?h=master-next

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.