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