Format for JDK 6/7 changeset comments?

iris.clark at sun.com iris.clark at sun.com
Tue Nov 6 06:16:54 UTC 2007


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