OK, I know I'm an intolerable nag, but I think it's time to introduce some consistency to our commit messages. Checkout out the last 5 commits to upstream and you'll see what I mean. I humbly suggest the following template:
[JIRA #] [Short Description] [Long Description]
This ends up looking something like this:
SWITCHYARD-510 Did some really cool stuff You won't believe how cool this was. I implemented: o Some x o More y o Lots of z
Here are the advantages I see with the above:
- One line log printing is informative and compact
- JIRA ID provides the ability to lookup more information
- Short description means you're not forced to lookup more information just to get a ballpark idea of what happened
- Separating the short and long description prevents the log description from being printed in one-line log printout but keeps it around when viewing complete log details.
The above is my view and I'm happy to change if the majority of folks want to do something different. No matter what the consensus, we should really try to be consistent between commits.
3 small comments:
- How about adding the full JIRA url to the issue? I like to add full URLs for things anywhere possible... git commits, pull requests etc. Makes it convenient.
- Short description should match that of the JIRA.
- Is there really a need to add the long description? The short description should give enough info unless it's really bad, no? On the rare occasion you might need more info, then follow the link to the JIRA (see#1 above ).
1. How about adding the full JIRA url to the issue? I like to add full URLs for things anywhere possible... git commits, pull requests etc. Makes it convenient.
Yeah, this is really the only difference between the way you do it and the way I do it. Personally, I find that the full URL tends to take up valuable room in my one-line commit message. Also, I know the root JIRA URL where I can just append the JIRA id. Now, I agree that not all people will have this knowledge, so I'm willing to go either way (full URL or just the id). To get an idea of what I'm talking about, here's a selection of recent commits:
03dc299dddaa05e97834f9e526f5ae75e58576b8 https://issues.jboss.org/browse/SWITCHYARD-178 TorqueBox POC - using SwitchYard f38ef2b7693fef53a87d66c755f5743a6a21f5b6 SWITCHYARD-176 Initial implementation of Forge support for bean, soap, and came 1d9b10d967b5972e1796362faffb9a26a1ba2386 SWITCHYARD-189 Update components based on deployment and activator changesbb34b0b1368f80adf6cae877cda133b34da41d43 SWITCHYARD-83 Updated component code to adjust to core API changes c9ed7a3dd16a989edb6af843ff42c1e394c80a07 SWITCHYARD-205 Fix checkstyle issues 0b865a862c3f21f54ddf84e9806d2a4b127ad92e https://issues.jboss.org/browse/SWITCHYARD-203 Merge @SwitchYardDeploymentScann 47ba22ad16a5f060b9a540442eec02f1ff00cea5 https://issues.jboss.org/browse/SWITCHYARD-185 Wire transformer implementation
2. Short description should match that of the JIRA.
Absoltely agree. Only exception is if the JIRA description is really long.
3. Is there really a need to add the long description? The short description should give enough info unless it's really bad, no? On the rare occasion you might need more info, then follow the link to the JIRA (see#1 above ).
No, the long description is completely optional. Only reason I mention it is to reduce the size of the one-line commit message which is what gets printed in both the GItHub commit history and the git log output with one-line pretty printing. Bottom line is that if you have a lot to say in the commit message (e.g. special build instructions), then do that in the long description.