Format for JDK 6/7 changeset comments?

[Kelly O'Hair]

I'm ok with this, a few minor questions:

   - Is a bugid any decimal integer, or is it a 7 digit number?
   - Will we check the bugid to make sure it's a valid bugid?
   - Does the synopsis have to match the synopsis in the bugtraq system?
   - How picky will we be on leading spaces on the line, or around the ':' character?
   - Can the Summary line be any length?
   - Should the reviewer name also be required to not be the changeset author?
   - Are multiple reviewer names blank or comma separated?
   - Any strict rules on the contributor email line? Company names ok?
   - Are tab characters allowed? ;^)

-kto

Mark Reinhold wrote:
> 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