r106 - /web/deps/dep3.mdwn

[hertzog at users.alioth.debian.org]

Author: hertzog
Date: Sat Sep 26 10:57:27 2009
New Revision: 106

URL: http://svn.debian.org/wsvn/dep/?sc=1&rev=106
Log:
Modify allowed structure to better cope with git format-patch

Add some aliases for widely-used field names.

Modified:
    web/deps/dep3.mdwn

Modified: web/deps/dep3.mdwn
URL: http://svn.debian.org/wsvn/dep/web/deps/dep3.mdwn?rev=106&op=diff
==============================================================================
--- web/deps/dep3.mdwn (original)
+++ web/deps/dep3.mdwn Sat Sep 26 10:57:27 2009
@@ -3,7 +3,7 @@
     Title: Patch Tagging Guidelines
     DEP: 3
     State: CANDIDATE
-    Date: 2009-09-07
+    Date: 2009-09-25
     Drivers: Raphael Hertzog <hertzog at debian.org>
     URL: http://dep.debian.net/deps/dep3
     Abstract:
@@ -47,11 +47,11 @@
 
 Structure
 ---------
-The meta-information would be stored in a set of RFC-2822-like
+The meta-information would be stored in one or two set(s) of RFC-2822-like
 fields (the difference with RFC-2822 is that newlines are meaningful in
 the Description field, they are not simple continuation characters).
-Those fields should start on the first non-empty line (after having
-stripped whitespace characters at the start and end of
+The first set of fields (headers) should start on the first non-empty line
+(after having stripped whitespace characters at the start and end of
 lines).
 
 For patch-systems like dpatch that require the patch to be a standalone
@@ -62,9 +62,12 @@
 they start with a space once "`#` " (hash followed by a space) has been
 stripped from the beginning.
 
-The set of fields ends on the first empty line. Free-form comments can
-follow and be used for any other information that does not fit in the
-structured content.
+Sets of fields always end on the first empty line. Free-form comments can
+follow and should be considered as supplementary lines of the long
+description (see detailed explanations of the field). A second-set of fields
+(pseudo-headers) can start on any new paragraph. A line containing 3 dashes
+(---) should stop the parsing: lines after it are not relevant part of the
+meta-information.
 
 Any parser that expect those fields in patch headers should also
 accept non-structured content and simply consider the whole content
@@ -78,10 +81,14 @@
 names are case-insensitive ("Fedora" and "fedora" refer to the same
 vendor).
 
-  * `Description` (required)
+  * `Description` or `Subject` (required)
 
     This obligatory field contains at least a short description on the
-    first line. Supplementary lines can be used to provide a longer
+    first line. When `Subject` is used, it is expected that the long
+    description is outside of the structured fields. With `Description` it
+    is possible to embed them in the field using continuation lines.
+
+    In both cases, the long description allows for a more verbose
     explanation of the patch and its history.
 
     This field should explain why the patch is vendor-specicific (ex:
@@ -143,7 +150,7 @@
     be "not-needed" to indicate that the patch must not be forwarded
     upstream (whereas "no" simply means that it has not yet been done).
 
-  * `Author` (optional)
+  * `Author` or `From` (optional)
 
     This field can be used to record the name and email of the patch author
     (ex: "`John Bear <foo at bar.net>`"). Its usage is recommended when the
@@ -153,7 +160,7 @@
     chance of being integrated upstream. This field can be used multiple
     times if several people authored the patch.
 
-  * `Reviewed-by` (optional)
+  * `Reviewed-by` or `Acked-by` (optional)
 
     This field can be used to document the fact that the patch has been
     reviewed by someone. It should list her name and email in the standard
@@ -171,7 +178,13 @@
 
 A patch cherry-picked from upstream:
 
-    Description: Fix regex problems with some multi-bytes characters
+    From: Ulrich Drepper <drepper at redhat.com>
+    Subject: Fix regex problems with some multi-bytes characters
+
+    * posix/bug-regex17.c: Add testcases.
+    * posix/regcomp.c (re_compile_fastmap_iter): Rewrite COMPLEX_BRACKET
+      handling.
+
     Origin: upstream, http://sourceware.org/git/?p=glibc.git;a=commitdiff;h=bdb56bac
     Bug: http://sourceware.org/bugzilla/show_bug.cgi?id=9697
     Bug-Debian: http://bugs.debian.org/510219
@@ -216,3 +229,8 @@
 * 2009-08-24: Add samples and mention difference with RFC-2822 related to
   the Description field.
 * 2009-09-07: Move to CANDIDATE status.
+* 2009-09-26: Modified structure to allow for 2 set of fields (headers and
+  pseudo-headers). Make Subject an alias of Description, From an alias of
+  Author and Acked-by an alias of Reviewed-by. All those changes allow for
+  a better compatibility with patches that are VCS changesets embedded in
+  mails (notably those generated by git format-patch).