James W. MacDonald wrote:
Robert recently suggested that I make a stab at a blog-based changelog
rather than the current monthly postings, sort of similar to what Duncan
Murdoch has done with the R NEWS and windows CHANGELOG.
The biggest difference between what is done for R and what I will be
doing for BioC is this; R-core does a really good job of writing
explanatory notes describing what the change was, and what it means for
the end user.
On the other hand, the commit messages that people use range from the
ridiculous to the sublime. Since I will no longer be parsing the commit
messages by hand, I will not be able to remove the more useless messages
that people tend to use, and these things will go straight to the
changelog for all to see.
So, first thing; if you don't want your section of the changelog to be
populated with things like 'WTF was I thinking?!@!?@!?' or 'Oops', or
the venerable 'commit' or better yet, the ever popular ' ', you will
want to actually use a commit message that means something with respect
to the commit you just made.
Now I know some of the commit messages are not intended for public
consumption, so there is a way out. If you prepend your commit message
with INTERNAL, then it will be scrubbed. Or at least I think it will
;-D. I'm using Python for the first time to do the parsing, so I am sure
there are bugs aplenty. Note that this INTERNAL thing is _by line_, so
if you do something like:
INTERNAL This is a commit message nobody should ever see.
But they can see this one.
Then the second part of the message _should_ get through. Note that you
need to use INTERNAL exactly, as it is always possible that someone
might use Internal at the beginning of a commit message that they want
published, so I am not doing any case-changing on the test for this string.
The changelog as it currently exists (with just one day of changes so
far) can be viewed here:
http://fgc.lsi.umich.edu/cgi-bin/blosxom.cgi
Please take a look and send me any suggestions.
Best,
Jim
Hmmm,
Here in Seattle, Seth had most of us making commit messages where the
1st line was a brief title describing the major contents of the change
and then there would be a line break followed by any of the gory details
that might be needed to carefully describe what the title meant. I like
this format because part of a commit message is to say briefly what
changes have taken place, and partly it's also a place to make personal
notes so that later on you can remember what you were thinking at the
time. So my 1st point is that by habit some of us already separate
these two with a linebreak.
Partly because I adopted this habit already and partly because I don't
want to live in constant fear of what might slip into my commit
messages, it might be nice if you just captured the 1st section and then
allowed us to tag any lines that fall below that linebreak with a
character if we want them to also be in the public eye (with the rest
remaining private by default)? Of course I could also tag the lower
stuff, but then I am typing lots of extra characters with each commit.
Marc