[Bioc-devel] All Package Maintainers Please README!

[Martin Morgan]

Jim --

I was actually writing identical sentiment (from across the hall), so
there's a second vote for just the first line (and filtering empty
first lines). Martin

Marc Carlson <mcarlson at fhcrc.org> writes:

> 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
>
> _______________________________________________
> Bioc-devel at stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel

-- 
Martin Morgan
Computational Biology Shared Resource Director
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N.
PO Box 19024 Seattle, WA 98109

Location: Arnold Building M2 B169
Phone: (206) 667-2793