Format for JDK 6/7 changeset comments?

[David Holmes - Sun Microsystems]

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
>