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

Diff of /web/deps/dep3.mdwn

Parent Directory | Revision Log | View Patch Patch

-revision 70 by hertzog,
Wed Jul 15 22:11:47 2009 UTC
+revision 109 by hertzog,
Thu Nov  5 07:45:35 2009 UTC
 Line 2
      Title: Patch Tagging Guidelines
      DEP: 3
-     State: DRAFT
+     State: CANDIDATE
-     Date: 2009-06-12
+     Date: 2009-10-05
      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 compliant
- fields. Those fields should start on the first non-empty line (after
+ The meta-information would be stored in one or two headers: sets of
- having stripped whitespace characters at the start and end of lines).
+ RFC-2822-like fields. (The difference with RFC 2822 is that newlines
+ are meaningful in the Description field, they are not simple
+ continuation characters). The first header 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
  script, the shebang line is ignored and it is possible to put those fields
-Line 59 
 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
-Line 71 
 Standard fields
+Line 78 
 Standard fields
  ---------------
  In the following section, `<Vendor>` can be "Debian" or the name
- of any other distribution that tracks the same problem/patch.
+ 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:
-Line 84 
 of any other distribution that tracks th
+Line 97 
 of any other distribution that tracks th
      upstream but has been rejected, the description should also document
      why it's kept and what were the reasons for the reject.
-   * `Origin` (required)
+     It's recommended to keep each line shorter than 80 characters.
+   * `Origin` (required except if `Author` is present)
-     This field should document the origin of the patch. It starts with a
+     This field should document the origin of the patch. In most cases, it
-     single keyword that can have the following standard values: "upstream"
+     should be a simple URL. For patches backported/taken from upstream, it
-     (in the case of a patch cherry-picked from the upstream VCS),
+     should point into the upstream VCS web interface when possible,
-     "backport" (in the case of an upstream patch that had to be modified
+     otherwise it can simply list the relevant commit identifier (it should
-     to apply on the current version), "vendor" for a patch created
+     be prefixed with "commit:" in that case). For other cases, one should
-     by Debian or another distribution vendor, or "other" for all other
+     simply indicate the URL where the patch was taken from (mailing list
-     kind of patches. It can be optionally followed by a colon with
+     archives, distribution bugtrackers, etc.) when possible.
-     leading/trailing spaces before/after it. In that case, all the content
-     after the colon contains supplementary information defining in more
+     The field can be optionaly prefixed with a single keyword followed by
-     details the origin of the patch. In most cases, it should be a simple
+     a comma and a space to categorize the origin. The allowed keywords are
-     URL. For patches backported/taken from upstream, it should point into
+     "upstream" (in the case of a patch cherry-picked from the upstream
-     the upstream VCS web interface when possible, otherwise it can simply
+     VCS), "backport" (in the case of an upstream patch that had to be
-     list the relevant commit identifier (it should be prefixed with
+     modified to apply on the current version), "vendor" for a patch
-     "commit:" in that case). For other cases, one should simply indicate
+     created by Debian or another distribution vendor, or "other" for all
-     the URL where the patch got grabbed (mailing list archives,
+     other kind of patches.
-     distribution bugtrackers, etc.) when possible.
-     In general, a user-created patch grabbed in a BTS should be tagged
+     In general, a user-created patch grabbed in a BTS should be
-     as "other". When copying a patch from another vendor, the
+     categorized as "other". When copying a patch from another vendor, the
      meta-information (and hence this field) should be kept if present, or
      created if necessary with a "vendor" origin.
+     If the `Author` field is present, the `Origin` field can be omitted
+     and it's assumed that the patch comes from its author.
    * `Bug-<Vendor>` or `Bug` (optional)
      It contains one URL pointing to the related bug (possibly fixed by the
-Line 134 
 of any other distribution that tracks th
+Line 151 
 of any other distribution that tracks th
      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.
+     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
      format (similar to the example given for the `Author` field). This
-     field can be used mutiple times if several persons reviewed the
+     field can be used multiple times if several people reviewed the
      patch.
    * `Last-Update` (optional)
      This field can be used to record the date when the meta-information
-     have been last updated. It should use the ISO date format
+     was last updated. It should use the ISO date format `YYYY-MM-DD`.
-     `YYYY-MM-DD`.
+ Sample DEP-3 compliant headers
+ ------------------------------
+ A patch cherry-picked from upstream:
+     From: Ulrich Drepper <drepper@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
+ A patch created by the Debian maintainer John Doe, which got forwarded
+ and rejected:
+     Description: Use FHS compliant paths by default
+      Upstream is not interested in switching to those paths.
+      .
+      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 <johndoe-guest@users.alioth.debian.org>
+     Last-Update: 2006-12-21
+ A vendor specific patch not meant for upstream submitted on
+ the BTS by a Debian developer:
+     Description: Workaround for broken symbol resolving on mips/mipsel
+      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
+     Bug-Debian: http://bugs.debian.org/265678
+     Author: Thiemo Seufer <ths@debian.org>
  Related links
  -------------
-Line 170 
 Changes
+Line 225 
 Changes
  * 2009-06-19: Replace Origin/Status/Patch with Origin/Forwarded. Add new
    fields Author and Last-Update. Rename Signed-off-by in Reviewed-by.
    Add a paragraph about the scope of the proposal.
+ * 2009-07-15: Make categorization in Origin optional. Make Origin optional
+   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.

 Legend:



Removed from v.70
 


changed lines


 
Added in v.109
 Legend:



Removed from v.70
 


changed lines


 
Added in v.109
-Removed from v.70
+Added in v.109

	ViewVC Help
Powered by ViewVC 1.1.5