Commit Messages

Commit Messages

by Dan Poltawski -
Number of replies: 6
Recently i've noticed an increasing trend to substitute commit messages simply for a pointer to the tracker via bug numbers.

I am the biggest fan of the tracker and the issue linking (particularly as it gives you a sort of fake 'changeset' to see how a bunch of commits relate). But I do not think good commit messages should be substituted for tracker links, they should compliment each other.

I subscribe to the cvs commit list for a few reasons; one of the main reasons is that it allows me to stay in touch with bugs. I only give commits a tiny glance, 99% aren't of relevance to me and I don't have time to read them. But glancing at the the commit message keeps me up to date with bugs being fixed. If its something I am really interested in then I will go read the bug. This means that later, when a user discovers a bug in an area i've seen fly by, i'll go hunting for the bug or examine recent changes before diving straight in for a fix.

So while getting stuck deep in the tracker is the best way to get the full details of an issue I still find commit messages immensely useful. You could see them as a way to entice people like me to go read your tracker issue! big grin

I can't remember seeing any guidelines in the docs about commit messages (other than please include a tracker issue). So perhaps it'd be good if we could come up with some suggestions.

What do you think?
Average of ratings: Useful (2)
In reply to Dan Poltawski

Re: Commit Messages

by Tim Hunt -
Picture of Core developers Picture of Documentation writers Picture of Particularly helpful Moodlers Picture of Peer reviewers Picture of Plugin developers
CVS commit messages must contain a bug number, however they should also contain a brief description of the fix. I am sure I have seen Martin say that several times.

I have just drafted http://docs.moodle.org/en/Development:CVS_for_developers#CVS_commit_messages. Feel free to amend it.
In reply to Tim Hunt

Re: Commit Messages

by Martin Dougiamas -
Picture of Core developers Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Plugin developers Picture of Testers
Correct, there should always be a short summary in the commit message, even just a one-liner.

Actually, I've not noticed any problem. Almost everyone seems to be doing the Right Thing.
In reply to Martin Dougiamas

Re: Commit Messages

by Valery Fremaux -

Well the fact is that some (few) commits will resolve a lot of pending little bugs. It is quite time spoiling to search within the tracker for all old bugs (althought we would have to mark them resolved...). This happens few, again. Another case is when the bug fixes touches one very light miswriting, one character patch ultra locally, on a bug no one noticed before. Should we put that effort in creating a bug entry before, commiting with bug reference, then go back to tracker for resolving ? (note that I'm, as we say in France, playing the "devil's advocate", as I'm convinced of the utility of a hypernotified procedure in such our big and nice team).

Query to MartinD : Global search becoming a straight and well bounded problematic in Moodle, could I get a separated issue category in the Tracker ? could save me much time in reviewing and reference management.

I don't know if there would be also need of a separated Forum, you'll feel it. Note that there are a small set of subjects that are pending to discuss on scalability, other module handling (such as assigments and user metadata searching), additional converters, better API for third party plugability in the search engine... that I would like to bring further.

Thanks Martin.   

In reply to Valery Fremaux

Re: Commit Messages

by Anthony Borrow -
Picture of Core developers Picture of Plugin developers Picture of Testers
Valery - Most of the time is what I think we are trying to provide guidelines for. There will always be exceptions. For a typo, I would think it is sufficient to simply comment fixed typo (even without creating a tracker issue) but the default way of thinking should be as is suggested here tracker and brief comment. Peace - Anthony
In reply to Valery Fremaux

Re: Commit Messages

by Martin Dougiamas -
Picture of Core developers Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Plugin developers Picture of Testers
I agree with Anthony, for very small typos there is no need to create bugs (just a short comment would be enough). Often these are a regression from another bug, so I usually just put the bug ID for that other existing bug anyway.

Issue category added!
http://tracker.moodle.org/browse/MDL/component/10300

Probably no need for a separate forum yet, most of those could be new feature issues in the tracker.
In reply to Martin Dougiamas

Re: Commit Messages

by Valery Fremaux -

Yop !!

I agree, this is a almost middleware level component ! We can manage it in tracker.