Format for JDK 6/7 changeset comments?

[Jesse Glick]

Mark Reinhold wrote:
> There's an important non-technical aspect of this issue that hasn't 
> really been discussed here: Giving credit where credit is due.

This is fine, but a CREDITS file can do the same job, probably more visibly.

I think this discussion is diverging from the basic question of why you 
would want to look at changeset comments at all. For me, there are two 
essential parts of a changeset comment:

1. What was changed and why, in case you want to know if the changeset 
is relevant to you.

2. More information, in case you have decided that the changeset 
probably is relevant to you.

For the second part, a bug number is enough; you can look up everything 
else there. For the first part, the text should be kept short, and 
should include only information necessary for a reader to decide whether 
they want to investigate the change. Key information:

1a. The visible symptom of the problem being fixed, in case the reader 
is experiencing the same or similar problem, perhaps in an earlier 
release, and wants to know if and when a fix was attempted.

1b. A summary of the changes being made to the code, in case the reader 
suspects that a recent coding error caused a regression and wants to 
track down the responsible commit.

Example:

"#1234567: selecting a combo box threw NPE. Fixed by partial rewrite of 
focus handling code in JComboBox."

Short and sweet. If (1a) I have encountered a NPE that I think is 
related to combo box implementation code, I will see this and 
immediately look up bug #1234567 and investigate further. Or, if (1b) I 
am having problems with focus on JComboBox's in recent builds, I will 
also see this and know to examine the diff to look for problematic code.

You may also be watching all commits in Swing code and have a special 
interest in focus handling or JComboBox.java, in which case both (1a) 
and (1b) might be useful as filters so you can decide which diffs to 
inspect closely. An email or RSS notification of the change could easily 
link to (or attach!) a web summary of the bug report, too.

In some cases the fix follows directly from the symptom and hardly needs 
special mention, e.g.

"#1234567: typo in javaws splash screen."

where the fix is simply to edit the message.

It is certainly important to have recorded somewhere who reviewed a 
proposed change, in case you are investigating effects of that change 
later and need to contact them. But I cannot think of a situation where 
I would be scanning the changelog of a software tree looking for changes 
reviewed by a particular person! This would just be noise. The same goes 
for details on how to reproduce the problem, a description of how the 
fix was verified, workarounds, alternative approaches that were 
suggested, etc. - these can all be found in the bug database.

-Jesse

-- 
jesse.glick at sun.com  netbeans.org  ant.apache.org  hudson.dev.java.net
             http://google.com/search?q=e%5E%28pi*i%29%2B1