Format for JDK 6/7 changeset comments?

[Mark Reinhold]

Here's a revised proposal that, I think, addresses all the issues that've
been raised since this discussion started a few weeks ago.

(Reminder: This proposal is only for the JDK 7 (and eventually JDK 6)
 code bases; others may adopt different conventions.)

A single change is described by a block of text of the following form:

  <bugid>: <synopsis-of-symptom>
  Summary: <summary-of-code-change>
  Reviewed-by: <reviewer>+
  Contributed-by: <contributor-email>

There can be more than one <bugid> line, but there must be at least one.

The summary line is optional, but authors are strongly encouraged to
include one if the nature of the change is not obvious from the synopsis.
It's just one line, meant to give the reader a clue as to how the code
changed.  A more complete description of the change belongs in the bug
report.

A reviewed-by line is required.  Reviewers must have the ability to deal
with any adverse consequences of the change, and so must themselves be
authors.  They're therefore identified by their OpenJDK usernames rather
than full e-mail addresses.

The contributed-by line is optional.

There will be exceptions for merge changesets, tag changesets, etc.

Example:

  1234567: NPE thrown on FileInputStream("")
  Summary: Rewrite precondition-checking code in io.c
  Reviewed-by: mr
  Contributed-by: Ben Bitdiddle <ben at bits.org>

If a changeset contains multiple unrelated changes (this is frowned upon,
but may happen from time to time) then its comment will contain multiple
blocks of the above form, separated by blank lines.

Other information that is often included in TeamWare putback comments is
not appropriate for Mercurial changeset comments.  This includes names of
test cases run, links to webrevs, pre-integration test results, approvals
from core release teams, etc.  Most of this type of information belongs
in the bug database, or possibly in ancillary databases (details TBD).

(FYI for non-TeamWare users: TeamWare "putback comments" don't have
 a direct analogue in Mercurial.  They're different from changeset
 comments; if Mercurial supported them then they'd be comments
 associated with a push operation.)

Comments?

- Mark