It is very important to record code contributions in a consistent -and parseable way. This allows us to write scripts which help us -figure out who has been actively contributing and how, so we can spot -potential new committers quickly. The Subversion project uses -human-readable but machine-parseable fields in log messages for this, -as described below.
+and parseable way. This allows us to write scripts to figure out who +has been actively contributing — and what they have +contributed — so we can spot potential new committers +quickly. The Subversion project uses human-readable but +machine-parseable fields in log messages to accomplish this.When committing a patch written by someone else, use -"Patch by: " at the beginning of a line:
+"Patch by: " at the beginning of a line to indicate the +author
Fix issue #1729: Don't crash because of a missing file.
@@ -1448,24 +1449,29 @@
(frobnicate_file): Check that file exists before frobnicating.
-If multiple people wrote the patch, name them all, one person per -line, making sure to start each continuation line with whitespace. If -you (the committer) were one of the people, list yourself as "me". -Thus:
+If multiple individuals wrote the patch, list them each on a +separate line — making sure to start each continuation +line with whitespace. Non-committers should be listed by name, if +known, and e-mail. Committers may be listed similarly, or by their +canonical usernames from COMMITTERS (the leftmost +column). Additionally, "me" is an acceptable shorthand for the person +actually committing the change.
Fix issue #1729: Don't crash because of a missing file.
Patch by: J. Random <jrandom@example.com>
Enrico Caruso <codingtenor@codingtenor.com>
+ jcommitter
me
* subversion/libsvn_ra_ansible/get_editor.c
(frobnicate_file): Check that file exists before frobnicating.
-If someone pointed out a problem or suggested the fix, but didn't -actually write the patch, use "Suggested by: ":
+If someone pointed out a problem or suggested the fix, but did not +actually write the patch, indicate the contribution with +"Suggested by: ":
Fix issue #1729: Don't crash because of a missing file.
@@ -1476,7 +1482,7 @@
(frobnicate_file): Check that file exists before frobnicating.
-If someone helped review the change, use "Review by: "
+If someone reviewed the change, use "Review by: "
Fix issue #1729: Don't crash because of a missing file.
@@ -1488,12 +1494,9 @@
-(As with "Patch by: ", you can name multiple people in -"Review by: " or "Suggested by: " via -whitespace-prefixed continuation lines.)
+All three fields may have multiple lines, and log messages may +contain any combination of the fields. -
Multiple fields in the same log message are fine, for example:
-
Fix issue #1729: Don't crash because of a missing file.
@@ -1502,13 +1505,14 @@
me
Suggested by: J. Random <jrandom@example.com>
Review by: Eagle Eyes <eeyes@example.com>
+ jcommitter
* subversion/libsvn_ra_ansible/get_editor.c
(frobnicate_file): Check that file exists before frobnicating.
-To give further details about a contribution, use a parenthetical -aside immediately after that field, for example:
+Further details about a contribution may be listed in a +parenthetical aside immediately after that field.
Fix issue #1729: Don't crash because of a missing file.
@@ -1521,14 +1525,7 @@
It is understood that a parenthetical aside immediately following a -field applies to that field, and that "me" refers to person who -committed this revision. You don't have to write "me", you can use -your name instead, if you're not tired of typing it. Also, although -the examples above use full name and email address, you can use a -committer's username to refer to that committer from any field. For -example, "Philip Martin <philip@codematters.co.uk>" and "philip" -would be equivalent. See the leftmost column of the COMMITTERS file -for canonical usernames.
+field applies to that field.Currently, these three fields
@@ -1538,17 +1535,16 @@ Review by: -are the only officially-supported crediting fields (where +
are the only officially supported crediting fields (where "supported" means scripts know to look for them), and they are widely -used in Subversion log messages. Future fields would probably also be -of the form "VERB by: ", and from time to time someone may -use a field that sounds official but really -isn't — there are a few instances of -"Reported by: ", for example. These are okay, but try to -use an official field, or a parenthetical aside, in preference to -making up your own field. Also, don't use "Reported by: " -when the reporter is already recorded in an issue; instead, just refer -to the issue.
+used in Subversion log messages. Future fields will probably be of +the form "VERB by: ", and from time to time someone may use +a field that sounds official but really is not — for +example, there are a few instances of "Reported by: ". +These are okay, but try to use an official field, or a parenthetical +aside, in preference to creating your own. Also, don't use +"Reported by: " when the reporter is already recorded in an +issue; instead, simply refer to the issue.Look over Subversion's existing log messages to see how to use these fields in practice. This command from the top of your trunk @@ -1558,12 +1554,12 @@ svn log | contrib/client-side/search-svnlog.pl "(Patch|Review|Suggested) by: " -
Note that the "Approved by: " field seen in some commits -is totally unrelated to these crediting fields (and is rarely parsed -by scripts). It is simply the standard syntax for indicating either -who approved a partial committer's commit outside their usual area, or -(in the case of merges to release branches) who voted for the change -to be merged.
+Note: The "Approved by: " field seen in some +commit messages is totally unrelated to these crediting fields (and is +rarely parsed by scripts). It is simply the standard syntax for +indicating either who approved a partial committer's commit outside +their usual area, or (in the case of merges to release branches) who +voted for the change to be merged.