[jbosstools-dev] On the topic of useful PR title/descriptions and git commit messages

[Max Rydahl Andersen]

Hey,

I'm seeing a tendency to just put the JIRA number + possible merge info in the topic of the pullrequest and git commit messages are long lines of text instead of properly formatted.

This makes it rather hard to look at the list of PR and git history and figure out what they are about plus they duplicate the merge info Github already knows about.

You might not be aware that git actually uses some rules/conventions on the git messages to make things like git log be readable and informative, git rebase and squash etc. can use the titles better and finally github uses the same conventions for their pull requests.

Thus if you treat the github pullrequest similar to how a good git commit comment is done (you can even copy/paste them if there is a 1-to-1 match) then we should be good.

Thus the basic conventions are:

1 line for title, max 50 characters and don't end with a '.'

Two new lines

paragraph of text, max 72 characters wide containing the necessary info/details.

And that 1 line title for our workflow is best started with the jira ID.
Thus a good minimal commit message would look like this:

JBIDE-1234 - hibernate tools 4 classloading is broken.

Because of changes in Hibernate 4 classloader we can no longer
do XYZ. Thus I've made it do ZXY instead.


For a PR you can either just copy verbatim the above or maybe add some refs/details:

JBIDE-1234 - hibernate tools 4 classloading is broken.

This should be applied not only to master but also branch jbosstools-4.0.x

With this github dashboard and git log messages becomes much more informative.

Links with more background/tips with respect to commits/messages/workflows:
http://who-t.blogspot.cz/2009/12/on-commit-messages.html
http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

/max