Format for JDK 6/7 changeset comments?

[Mark Reinhold]

(finally getting back to this topic)

> Date: Fri, 09 Nov 2007 13:01:41 -0800
> From: jim.a.graham at sun.com

> Why not both?  Why does it have to be one *or* the other?  I really
> don't get that aspect of these discussions.
> 
> ...
> 
> It's not like the information included in either location is somehow
> legally binding - it's all there just to help us get work done...

Having mulled this over during the last couple of weeks, and considering
related comments by Andrew Haley and Jesse Glick, I've come around to
agree that a short summary describing the change made in a changeset is
actually a good idea.

Most of us in the JDK team at Sun are used to browsing code histories
with the bug database close to hand.  Now that we've open-sourced the
code however, it's going to travel far and wide, in both time and space,
to many places where accessing the information in the bug database is
awkward (e.g., if it's only available in the form of archived e-mails)
if not simply impossible.

The code is also going to wind up being read by many people who don't
work in the same way that we Sun employees do, and who expect to see
short change summaries accompanying the code.

In this context, analyzing the question of what information belongs in
changeset comments strictly in terms of information architecture, which
frowns upon redundancy, is not the best approach.  The primary consumers
of this information are us humans, after all, not machines, so we should
optimize for our productivity even if it means defining an imperfect
information model.  We humans are actually pretty good at dealing with
redundancy and correcting for the occasional error that may creep into
seemingly-redundant information, so it's hard to see how an imperfect
model would really slow us down.

This view may strike some existing Sun contributors as heretical; sorry.
If a small change like this makes it easier for the downstream consumers
of our code to make good use of it, and is more consistent with their
working style, then the tiny effort required on our part is worthwhile.

(I'll post an updated proposal in a moment.)

- Mark