[Orca-checkins] r468 - trunk/orca

[blair at orcaware.com]

Author: blair at orcaware.com
Date: Wed Jul 20 20:00:40 2005
New Revision: 468

Modified:
   trunk/orca/README.DEVELOPERS

Log:
Include all of the 'Crediting' section from Subversion's HACKING
document at revision 15372 into Orca's README.DEVELOPERS file.

* README.DEVELOPERS
  (Crediting):
    New section copied from revision 15372 of
    http://svn.collab.net/repos/svn/trunk/HACKING .


Modified: trunk/orca/README.DEVELOPERS
==============================================================================
--- trunk/orca/README.DEVELOPERS	(original)
+++ trunk/orca/README.DEVELOPERS	Wed Jul 20 20:00:40 2005
@@ -20,6 +20,7 @@
    * Using page breaks
    * Other conventions
    * Writing log messages
+   * Crediting
    * Patch submission guidelines
    * Commit access
 
@@ -346,6 +347,127 @@
 
 
 
+Crediting
+=========
+
+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.
+
+When committing a patch written by someone else, use "Patch by: " at
+the beginning of a line:
+
+   Fix issue #1729: Don't crash because of a missing file.
+
+   Patch by: J. Random <jrandom at example.com>
+
+   * subversion/libsvn_ra_ansible/get_editor.c
+     (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:
+
+   Fix issue #1729: Don't crash because of a missing file.
+
+   Patch by: J. Random <jrandom at example.com>
+             Enrico Caruso <codingtenor at codingtenor.com>
+             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: ":
+
+   Fix issue #1729: Don't crash because of a missing file.
+
+   Suggested by: J. Random <jrandom at example.com>
+
+   * subversion/libsvn_ra_ansible/get_editor.c
+     (frobnicate_file): Check that file exists before frobnicating.
+
+If someone helped review the change, use "Review by:"
+
+   Fix issue #1729: Don't crash because of a missing file.
+
+   Review by: Eagle Eyes <eeyes at example.com>
+
+   * subversion/libsvn_ra_ansible/get_editor.c
+     (frobnicate_file): Check that file exists before frobnicating.
+
+(As with "Patch by: ", you can name multiple people in "Review by: "
+or "Suggested by: " via whitespace-prefixed continuation lines.)
+
+Multiple fields in the same log message are fine, for example:
+
+   Fix issue #1729: Don't crash because of a missing file.
+
+   Patch by: J. Random <jrandom at example.com>
+             Enrico Caruso <codingtenor at codingtenor.com>
+             me
+   Suggested by: J. Random <jrandom at example.com>
+   Review by: Eagle Eyes <eeyes at example.com>
+
+   * 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:
+
+   Fix issue #1729: Don't crash because of a missing file.
+
+   Patch by: J. Random <jrandom at example.com>
+   (Tweaked by me.)
+
+   * subversion/libsvn_ra_ansible/get_editor.c
+     (frobnicate_file): Check that file exists before frobnicating.
+
+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 at codematters.co.uk>" and "philip" would
+be equivalent.  See the leftmost column of the COMMITTERS file for
+canonical usernames.
+
+Currently, these three fields
+
+   Patch by:
+   Suggested by:
+   Review by:
+
+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.
+
+Look over Orca's existing log messages to see how to use these fields
+in practice.  This command from the top of your trunk working copy
+will help:
+
+wget http://svn.collab.net/repos/svn/trunk/contrib/client-side/search-svnlog.pl
+svn log | ./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.
+
+
+
 Patch submission guidelines
 ===========================