Format for JDK 6/7 changeset comments?
Kelly.Ohair at Sun.COM
Tue Dec 4 21:25:52 UTC 2007
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? ;^)
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
> 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.
> 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.)
> - Mark
More information about the discuss