I was contemplating adding the following verbage to the
ContributorWorkflow wiki page. Wanted to float it past the group first
to see if I got it correct.
====
A note about commit messages: you are highly encouraged to describe your
commit with enough detail for someone else to understand it. In doing
so, your commit message can consist of multiple lines. However, it also
is highly encouraged that the first line of your commit message not
exceed 40 characters. This is because some of the tooling that sits on
top of git (such as the httpd apps that let you browse the repo) assume
that the first line is top-level summary that is 40 characters or less.
Thus there will be highlighting and truncating of the commit message
using these assumptions, and it will look weird if these assumptions are
not kept. For example, here is a good example of a commit message:
(((
CB-1234: Fixed the whizbang widget
- added more sanity checking in the build script.
- fixed the API to return the correct value in the scenario where there
aren't any whizbangs present.
- corrected the documentation.
)))
Note that the first line does two things:
1) it is less than 40 characters. Subsequent lines after the first may
exceed 40 characters.
2) it references a Jira issue by its id. Commonly, there should be a
Jira issue open for defects and new features, and it is good practice
for commits to point to the Jira issue they are addressing.
