cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marcel Kinard <cmarc...@gmail.com>
Subject commit messages for newbies
Date Thu, 10 Jan 2013 15:22:35 GMT
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.


Mime
View raw message