Format for JDK 6/7 changeset comments?

[Kelly O'Hair]

With Mercurial the changeset defines the webrev, so no need to store one or refer to one.

The 'not appropriate' applies to approvals, certificates and data that relate
more to the release procedure than the code itself.

Teamware putback comments were not managed data like SCCS comments, so if you
considered them permanent, they were not.
With Mercurial, changeset comments is managed data and also the only comment.

Effectively we need to try and separate the management of the source base with
the management of the release.

-kto

Jeannette Hung wrote:
> Perhaps I'm behind on the overall discussion but why is:
> 
>  > Other information that is often included in TeamWare putback comments is
>  > not appropriate for Mercurial changeset comments.  This includes 
> names of
>  > test cases run, links to webrevs, pre-integration test results, 
> approvals
>  > from core release teams, etc.  Most of this type of information belongs
>  > in the bug database, or possibly in ancillary databases (details TBD).
> 
> not appropriate?  I really like seeing that information so it is obvious 
> what has been done to verify the fix.  I understand that it may not be 
> useful to everyone, but if it can be useful, why restrict this 
> information from being here?  Or is this more a matter of what is 
> required vs optional?
> 
> jeannette
> 
> Mark Reinhold wrote:
>> Here's a revised proposal that, I think, addresses all the issues that've
>> been raised since this discussion started a few weeks ago.
>>
>> (Reminder: This proposal is only for the JDK 7 (and eventually JDK 6)
>>  code bases; others may adopt different conventions.)
>>
>> A single change is described by a block of text of the following form:
>>
>>   <bugid>: <synopsis-of-symptom>
>>   Summary: <summary-of-code-change>
>>   Reviewed-by: <reviewer>+
>>   Contributed-by: <contributor-email>
>>
>> There can be more than one <bugid> line, but there must be at least one.
>>
>> The summary line is optional, but authors are strongly encouraged to
>> include one if the nature of the change is not obvious from the synopsis.
>> It's just one line, meant to give the reader a clue as to how the code
>> changed.  A more complete description of the change belongs in the bug
>> report.
>>
>> A reviewed-by line is required.  Reviewers must have the ability to deal
>> with any adverse consequences of the change, and so must themselves be
>> authors.  They're therefore identified by their OpenJDK usernames rather
>> than full e-mail addresses.
>>
>> The contributed-by line is optional.
>>
>> There will be exceptions for merge changesets, tag changesets, etc.
>>
>> Example:
>>
>>   1234567: NPE thrown on FileInputStream("")
>>   Summary: Rewrite precondition-checking code in io.c
>>   Reviewed-by: mr
>>   Contributed-by: Ben Bitdiddle <ben at bits.org>
>>
>> If a changeset contains multiple unrelated changes (this is frowned upon,
>> but may happen from time to time) then its comment will contain multiple
>> blocks of the above form, separated by blank lines.
>>
>> Other information that is often included in TeamWare putback comments is
>> not appropriate for Mercurial changeset comments.  This includes names of
>> test cases run, links to webrevs, pre-integration test results, approvals
>> from core release teams, etc.  Most of this type of information belongs
>> in the bug database, or possibly in ancillary databases (details TBD).
>>
>> (FYI for non-TeamWare users: TeamWare "putback comments" don't have
>>  a direct analogue in Mercurial.  They're different from changeset
>>  comments; if Mercurial supported them then they'd be comments
>>  associated with a push operation.)
>>
>> Comments?
>>
>> - Mark