/[dep]/web/deps/dep3.mdwn

Diff of /web/deps/dep3.mdwn

Parent Directory | Revision Log | View Patch Patch

-revision 99 by hertzog,
Tue Aug 25 23:43:36 2009 UTC
+revision 195 by plessy,
Sat Jul 23 08:05:51 2011 UTC
 Line 1
- [[meta title="DEP-3: Patch Tagging Guidelines"]]
+ [[!meta title="DEP-3: Patch Tagging Guidelines"]]
      Title: Patch Tagging Guidelines
      DEP: 3
-     State: DRAFT
+     State: CANDIDATE
-     Date: 2009-06-12
+     Date: 2009-11-26
      Drivers: Raphael Hertzog <hertzog@debian.org>
      URL: http://dep.debian.net/deps/dep3
      Abstract:
 Line 31 
 information about them (their origin/aut
  upstream, if they are meant to be debian specific or not, etc.). Thus the
  first step is to include those information in the patches when they are
  available so that tools like the [Patch Tracking
- System](http://patch-tracking.debian.net) can display them.
+ System](http://patch-tracker.debian.org) can display them.
  Scope and application
  ---------------------
 Line 47 
 information.
  Structure
  ---------
- The meta-information would be stored in a set of RFC-2822-like
- fields (the difference with RFC-2822 is that newlines are meaningful in
+ The meta-information would be stored in one or two headers: sets of
- the Description field, they are not simple continuation characters).
+ RFC-2822-like fields. (The difference with RFC 2822 is that newlines
- Those fields should start on the first non-empty line (after having
+ are meaningful in the Description field, they are not simple
- stripped whitespace characters at the start and end of
+ continuation characters). The first header should start on the first
- lines).
+ 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
  script, the shebang line is ignored and it is possible to put those fields
-Line 62 
 multi-line fields, the subsequent lines
+Line 63 
 multi-line fields, the subsequent lines
  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
+ A header always ends on the first empty line. Free-form comments can
- follow and be used for any other information that does not fit in the
+ follow and should be considered as supplementary lines of the long
- structured content.
+ description (see detailed explanations of the field). A second header
+ (the “pseudo-header”) 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
+ accept non-structured content and simply append the non-structured
- to be the value of the `Description` field.
+ content to the value of the `Description` field.
+ All the meta-information must be UTF-8 encoded. When the patch itself
+ contains non-UTF-8 characters, it's recommended to stick to ASCII for the
+ meta-information.
  Standard fields
  ---------------
-Line 78 
 of any other distribution that tracks th
+Line 86 
 of any other distribution that tracks th
  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:
-Line 143 
 vendor).
+Line 155 
 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 <foo@bar.net>`"). Its usage is recommended when the
+     (ex: "`John Bear <foo@example.com>`"). Its usage is recommended when the
      patch author did not add copyright notices for his work in the patch
      itself. It's also a good idea to add this contact information when
      the patch needs to be maintained over time because it has very little
      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
+     reviewed and approved by someone. It should list her name and email in
-     format (similar to the example given for the `Author` field). This
+     the standard format (similar to the example given for the `Author`
-     field can be used multiple times if several people reviewed the
+     field). This field can be used multiple times if several people
-     patch.
+     reviewed the patch.
    * `Last-Update` (optional)
      This field can be used to record the date when the meta-information
      was last updated. It should use the ISO date format `YYYY-MM-DD`.
+   * `Applied-Upstream` (optional)
+     This field can be used to document the fact that the patch has been
+     applied upstream. It may contain the upstream version expected to
+     contain this patch, or the URL or commit identifier of the upstream
+     commit (with commit identifiers prefixed with "commit:", as in the
+     `Origin` field), or both separated by a comma and a space.
  Sample DEP-3 compliant headers
  ------------------------------
  A patch cherry-picked from upstream:
-     Description: Fix regex problems with some multi-bytes characters
+     From: Ulrich Drepper <drepper@redhat.com>
-     Origin: upstream: http://sourceware.org/git/?p=glibc.git;a=commitdiff;h=bdb56bac
+     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
- A patch created by the the Debian maintainer John Doe, which got forwarded
+ A patch created by the Debian maintainer John Doe, which got forwarded
  and rejected:
      Description: Use FHS compliant paths by default
-Line 185 
 and rejected:
+Line 211 
 and rejected:
       But we will continue using them in Debian nevertheless to comply with
       our policy.
      Forwarded: http://lists.example.com/oct-2006/1234.html
-     Author: John Doe <john@foobar.com>
+     Author: John Doe <johndoe-guest@users.alioth.debian.org>
      Last-Update: 2006-12-21
  A vendor specific patch not meant for upstream submitted on
-Line 195 
 the BTS by a Debian developer:
+Line 221 
 the BTS by a Debian developer:
       The correct fix will be done in etch and it will require toolchain
       fixes.
      Forwarded: not-needed
-     Origin: vendor: http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=80;bug=265678
+     Origin: vendor, http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=80;bug=265678
      Bug-Debian: http://bugs.debian.org/265678
      Author: Thiemo Seufer <ths@debian.org>
+ A patch submitted and applied upstream:
+     Description: Fix widget frobnication speeds
+      Frobnicating widgets too quickly tended to cause explosions.
+     Forwarded: http://lists.example.com/2010/03/1234.html
+     Author: John Doe <johndoe-guest@users.alioth.debian.org>
+     Applied-Upstream: 1.2, http://bzr.example.com/frobnicator/trunk/revision/123
+     Last-Update: 2010-03-29
  Related links
  -------------
-Line 215 
 Changes
+Line 250 
 Changes
    if Author is present.
  * 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 (the header and
+   pseudo-header). 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).
+ * 2009-10-05: Clarify the distinction between header and field, by the
+   precedent set in RFC 2822.
+ * 2009-11-09: Clarify how non-structured paragraph are merged in the
+   Description. Make it explicit that Reviewed-by and Acked-by imply
+   approval of the change.
+ * 2009-11-26: Enforce UTF-8 usage for the meta-information and recommend
+   ASCII when the patch contains non-UTF-8 characters.
+ * 2010-04-16: Add the Applied-Upstream field.

 Legend:



Removed from v.99
 


changed lines


 
Added in v.195
 Legend:



Removed from v.99
 


changed lines


 
Added in v.195
-Removed from v.99
+Added in v.195

	ViewVC Help
Powered by ViewVC 1.1.5