Hello,
following the recent comments on DEP-3 concerning its usage with git
format-patch I modified it (the patch is below). The resulting version
is on http://dep.debian.net/deps/dep3/. Feel free to comment if you see
further improvements.
--- a/web/deps/dep3.mdwn
+++ b/web/deps/dep3.mdwn
@@ -3,7 +3,7 @@
Title: Patch Tagging Guidelines
DEP: 3
State: CANDIDATE
- Date: 2009-09-07
+ Date: 2009-09-25
Drivers: Raphael Hertzog <hert...@debian.org>
URL: http://dep.debian.net/deps/dep3
Abstract:
@@ -47,11 +47,11 @@ information.
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 @@ multi-line fields, the subsequent lines should start with
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 @@ of any other distribution that tracks the same
problem/patch. Vendor
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 @@ vendor).
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 <f...@bar.net>`"). Its usage is recommended when the
@@ -153,7 +160,7 @@ vendor).
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 @@ Sample DEP-3 compliant headers
A patch cherry-picked from upstream:
- Description: Fix regex problems with some multi-bytes characters
+ From: Ulrich Drepper <drep...@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 @@ Changes
* 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).
--
Raphaël Hertzog
--
To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
