Format for JDK 6/7 changeset comments?

[Matt Fowles]

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
> >
>