Format for JDK 6/7 changeset comments?
Dmitri Trembovetski
Dmitri.Trembovetski at Sun.COM
Tue Nov 6 17:34:18 UTC 2007
Kelly O'Hair wrote:
> And I think using the changeset comment for that is the wrong place to
> put it.
I agree with Kelly here. This kind of information should be in the
bug evaluation.
>>> 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.
Then why not the synopsis of the bug? We do this all the time.
Thanks,
Dmitri
>
> -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
>>>>
More information about the discuss
mailing list