[ovs-dev] [PATCH] CONTRIBUTING: Describe commonly used tags; introduce Reported-at.

[Ben Pfaff]

This is partly documentation of how patches are tagged in practice in Open
vSwitch.  The bits at the end about "Reported-at:" and "VMware-BZ:" are
an attempt to influence future practices; I cannot say how successful they
will be.

I am not sure whether these key-value pairs at the end of commit messages
are actually commonly called "tags".  I'm happy to use a different term if
that one seems wrong.

Reported-by: Flavio Leitner <fbl at redhat.com>
Reported-at: http://openvswitch.org/pipermail/dev/2014-June/040952.html
Signed-off-by: Ben Pfaff <blp at nicira.com>
---
 CONTRIBUTING |  112 ++++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 101 insertions(+), 11 deletions(-)

diff --git a/CONTRIBUTING b/CONTRIBUTING
index d755186..64ca845 100644
--- a/CONTRIBUTING
+++ b/CONTRIBUTING
@@ -82,6 +82,8 @@ The description should include:
         - Testing that you performed (or testing that should be done
           but you could not for whatever reason).
 
+        - Tags (see below).
+
 There is no need to describe what the patch actually changed, if the
 reader can see it for himself.
 
@@ -94,21 +96,109 @@ If you, the person sending the patch, did not write the patch
 yourself, then the very first line of the body should take the form
 "From: <author name> <author email>", followed by a blank line.  This
 will automatically cause the named author to be credited with
-authorship in the repository.  If others contributed to the patch, but
-are not the main authors, then please credit them as part of the
-description (e.g. "Thanks to Bob J. User for reporting this bug.").
+authorship in the repository.
+
+Tags
+----
+
+The description ends with a series of tags, written one to a line as
+the last paragraph of the email.  Each tag indicates some property of
+the patch in an easily machine-parseable manner.
+
+Examples of common tags follow.
+
+    Signed-off-by: Author Name <author.name at email.address...>
+
+        Informally, this indicates that Author Name is the author or
+        submitter of a patch and has the authority to submit it under
+        the terms of the license.  The formal meaning is to agree to
+        the Developer's Certificate of Origin (see below).
+
+        If the author and submitter are different, each must sign off.
+        If the patch has more than one author, all must sign off.
+
+        Signed-off-by: Author Name <author.name at email.address...>
+        Signed-off-by: Submitter Name <submitter.name at email.address...>
+
+    Co-authored-by: Author Name <author.name at email.address...>
+
+        Git can only record a single person as the author of a given
+        patch.  In the rare event that a patch has multiple authors,
+        one must be given the credit in Git and the others must be
+        credited via Co-authored-by: tags.  (All co-authors must also
+        sign off.)
+
+    Acked-by: Reviewer Name <reviewer.name at email.address...>
+
+        Reviewers will often give an Acked-by: tag to code of which
+        they approve.  It is polite for the submitter to add the tag
+        before posting the next version of the patch or applying the
+        patch to the repository.  Quality reviewing is hard work, so
+        this gives a small amount of credit to the reviewer.
+
+        Not all reviewers give Acked-by: tags when they provide
+        positive reviews.  It's customary only to add tags from
+        reviewers who actually provide them explicitly.
+
+    Tested-by: Tester Name <reviewer.name at email.address...>
+
+        When someone tests a patch, it is customary to add a
+        Tested-by: tag indicating that.  It's rare for a tester to
+        actually provide the tag; usually the patch submitter makes
+        the tag himself in response to an email indicating successful
+        testing results.
+
+    Reported-by: Reporter Name <reporter.name at email.address...>
+
+        When a patch fixes a bug reported by some person, please
+        credit the reporter in the commit log in this fashion.  Please
+        also add the reporter's name and email address to the list of
+        people who provided helpful bug reports in the AUTHORS file at
+        the top of the source tree.
+
+        Fairly often, the reporter of a bug also tests the fix.
+        Occasionally one sees a combined "Reported-and-tested-by:" tag
+        used to indicate this.  It is also acceptable, and more
+        common, to include both tags separately.
+
+        (If a bug report is received privately, it might not always be
+        appropriate to publicly credit the reporter.  If in doubt,
+        please ask the reporter.)
+
+    Requested-by: Requester Name <requester.name at email.address...>
+    Suggested-by: Suggester Name <suggester.name at email.address...>
+
+        When a patch implements a request or a suggestion made by some
+        person, please credit that person in the commit log in this
+        fashion.  For a helpful suggestion, please also add the
+        person's name and email address to the list of people who
+        provided suggestions in the AUTHORS file at the top of the
+        source tree.
+
+        (If a suggestion or a request is received privately, it might
+        not always be appropriate to publicly give credit.  If in
+        doubt, please ask.)
+
+    Reported-at: <URL>
+
+        If a patch fixes or is otherwise related to a bug reported in
+        a public bug tracker, please include a reference to the bug in
+        the form of a URL to the specific bug, e.g.:
+
+        Reported-at: https://bugs.debian.org/743635
 
-Please sign off on the patch as a submitter, and be sure to have the
-author(s) sign off for patches that you did not author.
+        This is also an appropriate way to refer to bug report emails
+        in public email archives, e.g.:
 
-Simply include your name and email address as the last line of the commit
-message before any comments (and author too, if that is not you):
+        Reported-at: http://openvswitch.org/pipermail/dev/2014-June/040952.html
 
-Signed-off-by: Author Name <author.name at email.address...>
-Signed-off-by: Submitter Name <submitter.name at email.address...>
+    VMware-BZ: #1234567
 
-By doing this, you are agreeing to the Developer's Certificate of Origin
-(see below for more details).
+        If a patch fixes or is otherwise related to a bug reported in
+        a private bug tracker, you may include some tracking ID for
+        the bug for your own reference.  Please include some
+        identifier to make the origin clear, e.g. "VMware-BZ" in this
+        case refers to VMware's internal Bugzilla instance.
 
 Developer's Certificate of Origin
 ---------------------------------
-- 
1.7.10.4