Good Commit Message Guidelines

From AbiWiki

These are unofficial guidelines, offered by Ryan as a formalization/enumeration of unspoken etiquette.

If you are committing, be sure to enter a good commit message before making the commit. A "good commit message" can be in many forms, but a few basic guidelines can help improve and standardize the quality of commit messages.

Content Guidelines

A good commit message:

• Has a short description as its first line, followed by a blank line (or is just a single line if it can be both brief and complete)
• Describes the changes and rationale, at a high level (be thorough but remember that this is a commit message, not source code comments)
• Mentions any bugs ("Fixes bug#999999") fixed by the included changes.
• Mentions any caveats of the changes, unintended side effects, etc.
• Offers a brief acknowledgement to other developers who contributed substantially to the patch, debugging process, etc.
  • Commit message should include: "Thanks to {name, optionally 'for help with ___'}+" - but don't go overboard: see Style Guidelines.

Guidelines regarding the word "Backport"

A good commit message:

• Includes the phrase "Please backport" if the change can safely be made to the stable series as well (generally only small bug fixes), and should be applied to the stable tree and included in the next stable release (don't do this yourself except as below)
• Does not otherwise mention "backport" unless:
  • it is a bad idea to backport this change which otherwise might look safe to backport to a maintainer coping with developers not always labeling backportable commits (a bugfix that doesn't apply to stable, an apparently small feature that actually requires a large change)
    • Commit message should include: "Do not backport - {reason}"
  • this change should only be backported if another change is backported. Please consider why you are putting effectively a single change in two commits: unless there's a good reason (such as needed to change both the abiword and abiword-msvc2008 SVN modules), reconsider committing this particular patch. If you want to share partial progress on a large change, create a SVN branch for that change, which you can commit frequently to and merge back into trunk when complete.
    • Commit message should include: "Backport only if r{SVN revision of other change} is backported" for a previous commit, or "Backport only if upcoming commit about {a short title for the future commit} is backported", for an upcoming commit, as appropriate.
  • you have manually backported this change. (Don't do this without a very good reason! If a change is non-trivial to backport, you can do it but it's best to ask first. All initial changes should be made to a single-purpose branch of trunk or trunk itself unless the change only applies to the stable branch. If you need a trunk change backported before you can make a stable-only change, backport that change locally only (waiting to commit until the backport is made by the maintainer) and/or email the stable source tree maintainer to see if backports can be completed now before a release, currently Marc Maurer (uwog), with a reason and optionally a bribe for speedier service ;) )
    • Commit message should include: "Do not backport - manually backported as r{SVN revision of commit to stable}" or "Do not backport - I will manually backport." as appropriate for the commit to trunk, and "Manual backport of r{SVN revision of commit to trunk}" or "Manual backport of my upcoming trunk commit" as appropriate for the commit to stable.
    • If you must manually backport, it's best to first make the commit to trunk, then to stable.
    • Manual backports must have this noted in both the trunk and stable commits, and a notification must be emailed to the developer email list and/or to Marc personally ("and" preferred) with both commit revision numbers so that the change merge system can be updated to reflect this.

Style Guidelines

A good commit message:

• is concise, clear, and if necessary, followed by an email to the developer mailing list (ideally, subscribe to the svn commit mailing list and reply to the email with your commit) with any details that didn't fit in the commit message, aren't appropriate for inline documentation in the source, but are nonetheless important to mention to other developers and archive publicly with the mailing lists.