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

Diff of /web/deps/dep3.mdwn

Parent Directory | Revision Log | View Patch Patch

-revision 65 by hertzog,
Fri Jun 19 09:16:01 2009 UTC
+revision 102 by hertzog,
Mon Sep  7 20:50:11 2009 UTC
 Line 2
      Title: Patch Tagging Guidelines
      DEP: 3
-     State: DRAFT
+     State: CANDIDATE
-     Date: 2009-06-12
+     Date: 2009-09-07
      Drivers: Raphael Hertzog <hertzog@debian.org>
      URL: http://dep.debian.net/deps/dep3
      Abstract:
 Line 33 
 first step is to include those informati
  available so that tools like the [Patch Tracking
  System](http://patch-tracking.debian.net) can display them.
+ Scope and application
+ ---------------------
+ The usage of this format is highly recommended but as long as it's not
+ endorsed by the Debian policy, it will not be required. It is however
+ expected that tools like lintian will be modified to recommend adding
+ those information in patches. As the technical impact on package is null,
+ there's no need to organize a time-limited transition. All maintainers
+ can start using this format while doing their regular uploads, there's no
+ need to upload new revisions of packages just for adding those
+ information.
  Structure
  ---------
- The meta-information would be stored in a set of RFC-2822 compliant
+ The meta-information would be stored in a set of RFC-2822-like
- fields. Those fields should start on the first non-empty line (after
+ fields (the difference with RFC-2822 is that newlines are meaningful in
- having stripped whitespace characters at the start and end of lines).
+ 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
+ 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
  in comments. The line should then follow the format "`# <field>`". For
  multi-line fields, the subsequent lines should start with
- "`#`&nbsp;&nbsp;" (dash followed by two spaces) so that
+ "`#`&nbsp;&nbsp;" (hash followed by two spaces) so that
- they start with a space once "`#` " (dash followed by a space) has been
+ 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.
+ Any parser that expect those fields in patch headers should also
+ accept non-structured content and simply consider the whole content
+ to be the value of the `Description` field.
  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)
-Line 69 
 of any other distribution that tracks th
+Line 89 
 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. In most cases, it
+     should be a simple URL. For patches backported/taken from upstream, it
+     should point into the upstream VCS web interface when possible,
+     otherwise it can simply list the relevant commit identifier (it should
+     be prefixed with "commit:" in that case). For other cases, one should
+     simply indicate the URL where the patch was taken from (mailing list
+     archives, distribution bugtrackers, etc.) when possible.
+     The field can be optionaly prefixed with a single keyword followed by
+     a comma and a space to categorize the origin. The allowed keywords are
+     "upstream" (in the case of a patch cherry-picked from the upstream
+     VCS), "backport" (in the case of an upstream patch that had to be
+     modified to apply on the current version), "vendor" for a patch
+     created by Debian or another distribution vendor, or "other" for all
+     other kind of patches.
+     In general, a user-created patch grabbed in a BTS should be
+     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.
-     This field should document the origin of the patch. It starts with a
+     If the `Author` field is present, the `Origin` field can be omitted
-     single keyword that can have the following standard values: "upstream"
+     and it's assumed that the patch comes from its author.
-     (in the case of a patch cherry-picked from the upstream VCS),
-     "backport" (in the case of an upstream patch that had to be modified
-     to apply on the current version), "vendor" for a patch created
-     by Debian or another distribution vendor, or "other" for all other
-     kind of patches. It can be optionally followed by a colon with
-     leading/trailing spaces before/after it. In that case, all the content
-     after the colon contains supplementary information defining in more
-     details the origin of the patch. In most cases, it should be a simple
-     URL. For patches backported/taken from upstream, it should point into
-     the upstream VCS web interface when possible, otherwise it can simply
-     list the relevant commit identifier (it should be prefixed with
-     "commit:" in that case). For other cases, one should simply indicate
-     the URL where the patch got grabbed (mailing list archives,
-     distribution bugtrackers, etc.) when possible.
    * `Bug-<Vendor>` or `Bug` (optional)
-Line 95 
 of any other distribution that tracks th
+Line 124 
 of any other distribution that tracks th
      bug tracker. Those fields can be used multiple times if several
      bugs are concerned.
+     The vendor name is explicitely encoded in the field name so that
+     vendors can share patches among them without having to update the
+     meta-information in most cases. The upstream bug URL is special
+     cased because it's the central point of cooperation and it must
+     be easily distinguishable among all the bug URLs.
    * `Forwarded` (optional)
      Any value other than "no" or "not-needed" means that the patch
-Line 115 
 of any other distribution that tracks th
+Line 150 
 of any other distribution that tracks th
      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)
      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:
+     Description: Fix regex problems with some multi-bytes characters
+     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 <john@foobar.com>
+     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 143 
 Changes
+Line 210 
 Changes
  * 2009-06-12: Initial draft by Raphaël Hertzog.
  * 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.

 Legend:



Removed from v.65
 


changed lines


 
Added in v.102
 Legend:



Removed from v.65
 


changed lines


 
Added in v.102
-Removed from v.65
+Added in v.102

	ViewVC Help
Powered by ViewVC 1.1.5