Format for JDK 6/7 changeset comments?

[Kelly O'Hair]

And I think using the changeset comment for that is the wrong place to put it.

-kto

Matt Fowles wrote:
> All~
> 
> I agree with David that there needs to be a place to explain technical
> details of what changed and not just the motivation for why it
> changed.
> 
> Matt
> 
> On 11/6/07, David Holmes - Sun Microsystems <David.Holmes at sun.com> wrote:
>> Hi Iris,
>>
>> In our current scheme using teamware we have two levels of "comments".
>> First there is the sccs delta comment; then there is the putback comment.
>>
>> Different groups use different conventions for what information is used
>> for each kind of comment.
>>
>> One of the things we do with Hotspot putback comments (and sometimes
>> sccs comments) is include, if deemed necessary, technical information
>> about the change. This is particularly pertinent as many of our bug
>> synopses don't shed any light on the nature of the bug let alone the
>> nature of the fix. So the putback comment might give an overview of the
>> general nature of the fix, while the sccs comment might be more specific
>> regarding how the fix impacted a given file. The CR # and synopsis is
>> generally always included to give context/traceability.
>>
>> So one thing I would hope to see in these changeset comments is this
>> technical description - assuming there isn't some other more suitable
>> place for this commentary.
>>
>> Cheers,
>> David Holmes
>>
>> iris.clark at sun.com said the following on  6/11/07 04:16 PM:
>>> Hi.
>>>
>>> As you know, the experimental OpenJDK repositories for JDK 7 are
>>> available [1].  In anticipation of getting the repositories live, we
>>> need to decide what our convention for changeset comments should be.
>>> The required format of the comments will be enforced whenever the
>>> changeset is pushed into the JDK 6/7 master or group repository
>>> forests.  Other Projects may copy these conventions, adopt some other
>>> conventions, or have no conventions, depending upon their goals.
>>>
>>> In the old system, depending on the group integration tree, several
>>> formats were in use.  Here's the common information:
>>>
>>>   - name of the person making the change
>>>   - bugid (a 7-digit number allocated by the Sun bug database)
>>>   - complete synopsis of the bug
>>>   - comma-separated list of reviewers of the change (typically
>>>     either username or e-mail address)
>>>
>>> Optional information which appears in some trees includes:
>>>
>>>   - information about existenace or feasibility of regression/unit
>>>     tests
>>>   - pointer to associated webrev
>>>   - list of approvals
>>>   - contributor acknowledgements
>>>
>>> Though we expect most changesets to contain updates for a single bug,
>>> our convention should easily accommodate changesets involving multiple
>>> bugs.  Based on informal discussions, here's a potential format:
>>>
>>>   The number of lines in the changeset is equal to the number of bugs.
>>>   For each bug, there is a line of the following form:
>>>
>>>     <id>: <synopsis> [<reviewer>*]
>>>
>>>   where
>>>
>>>     <id>        - a 7-digit bugid allocated by the Sun bug database
>>>     <synposis>  - the complete synposis for the bugid
>>>     <reviewer>* - a comma separated list of reviewers of the change
>>>                   (repository userid)
>>>
>>>   The name of the person submitting the change is the user who created
>>>   the changeset.
>>>
>>>   For example:
>>>
>>>      4853841: Nervous text demo displays wrong version [iris, duke]
>>>
>>> This covers the common information but is that sufficient?  I think
>>> that the optional information regarding testing, webrev, and approvals
>>> should be contained in the bug, but what about contributor
>>> acknowledgements?  Perhaps something along these lines is more
>>> suitable:
>>>
>>>   For each bug there is a block of the following form:
>>>
>>>     <id>: <synopsis>
>>>     Review: <reviewer>*
>>>     Credit: <acknowledgement>*
>>>
>>>   where
>>>
>>>      <id>, <synopsis>, <reviewers>
>>>                 - described above
>>>      <acknowledgement>
>>>                 - arbitrary string of contributor acknowledgments
>>>
>>>   The first two lines are required.  The third is optional.  The name
>>>   of the person submitting the change is user who created the
>>>   changeset.
>>>
>>>   For example:
>>>
>>>     4853841: Nervous text demo displays wrong version
>>>     Review: iris, duke
>>>     Credit: mr - for extending the demo to accept arguments
>>>
>>> I favor the compactness of the first format; but the second is more
>>> extensible and gives us a simple means to recognise key contributions
>>> besides simple authorship or review.
>>>
>>> What do you think?
>>>
>>> Thanks,
>>> iris
>>>
>>> [1] http://hg.openjdk.java.net
>>>