Proposed revised format for JDK commit messages

[joe darcy]

Hello,

As documented in http://openjdk.java.net/guide/producingChangeset.html, 
the format for a Mercurial changeset comment has been

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

where the "Summary:" and "Contributed-by: " lines are syntactically 
optional. In more detail from the Developers Guide:

> There may 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 are therefore identified by their OpenJDK 
> usernames rather than full e-mail addresses.
>
> The contributed-by line is optional. If present, it is a list of 
> comma-separated email addresses. It should be included only when the 
> author or authors of the change do not have commit rights to the 
> target repository and thus would not otherwise receive acknowledgment.


[...]

> The required format of the comments will be enforced whenever the 
> changeset is pushed into the JDK master or team repository forests. 
> Other Projects may copy these conventions, adopt some other 
> conventions, or have no conventions, depending upon their goals

The syntax check of this format is enforced on the JDK repos using jcheck.

Slightly more formally, the existing commit message can be described by 
an EBNF-style grammar as:

   JdkHgCommitMessage : BugIdLine+ SummaryLine? ReviewersLine 
ConstributedByLine?

   BugIdLine : /[0-9]{8}/ ": " Text

   SummaryLine : "Summary: " Text

   ReviewersLine : "Reviewed-by: " Username (", " Username)* "\n"

   ContributedByLine : "Contributed-by: " Text

   Username : /[a-z]+/

   Text : /[^\n]+/ "\n"

This format has served adequately over the years; although it doesn't 
accurately model some more complex scenarios, such as a patch 
co-authored by several people. The commit message is part of the hash of 
a change. Therefore, changing an SCM is one of the few times the format 
of the message can be uniformly changed without triggering a new set of 
hashes (since there will already by a new set of hashes from changing 
the SCM)

Git tooling generally expects commits to have a subject and git requires 
an email field. This argues for adjustments in the commit format.

One possibility is:

   ProposedJdkGitCommitMessage : BugIdLine+ BlankLine SummaryLine? 
ReviewersLine CoAuthorsLine+

   BugIdLine : /[0-9]{8}/ ": " Text

   SummaryLine : "Summary: " Text

   ReviewersLine : "Reviewed-by: " Username (", " Username)* "\n"

   ContributedByLine : "Contributed-by: " Text

   BlankLine = "\n"

   Username : /[a-z]+/

   Text : /[^\n]+/ "\n"

A simple example:

Current:

     8210283: Support git as an SCM alternative in the build
     Reviewed-by: ihse, ehelin

Proposed:

     8210283: Support git as an SCM alternative in the build

     Reviewed-by: ihse, ehelin

The only difference in a simple case is the addition of a blank line 
between the bug ids and the reviewer information. The initial bug id 
line(s) before the the first blank line serve as the git subject field.

A more complicated example:

Current:

     8167108: inconsistent handling of SR_lock can lead to crashes
     Summary: Add Thread Safe Memory Reclamation (Thread-SMR) mechanism.
     Reviewed-by: coleenp, dcubed, dholmes, eosterlund, gthornbr, 
kbarrett, rehn, sspitsyn, stefank
     Contributed-by: daniel.daugherty at oracle.com, 
erik.osterlund at oracle.com, robbin.ehn at oracle.com

Proposed:

     8167108: inconsistent handling of SR_lock can lead to crashes

     Add Thread Safe Memory Reclamation (Thread-SMR) mechanism.

     Reviewed-by: coleenp, dcubed, dholmes, eosterlund, gthornbr, 
kbarrett, rehn, sspitsyn, stefank
     Co-authored-by: Erik Osterlund <erik.osterlund at oracle.com>
     Co-authored-by: Robbin Ehn <robbin.ehn at oracle.com>
     Co-authored-by: Igor Ignatyev <igor.ignatyev at oracle.com>

A "Co-authored-by" field is recognized by popular git hosting providers.

A JDK 12 repo whose commits have been converted to this format will be 
available shortly.

Comments?

Thanks,

-Joe