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

Diff of /web/deps/dep3.mdwn

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 69 by hertzog, Mon Jun 29 20:52:59 2009 UTC revision 246 by hertzog, Mon Jan 16 11:20:55 2012 UTC
# Line 1  Line 1 
1  [[meta title="DEP-3: Patch Tagging Guidelines"]]  [[!meta title="DEP-3: Patch Tagging Guidelines"]]
2    
3      Title: Patch Tagging Guidelines      Title: Patch Tagging Guidelines
4      DEP: 3      DEP: 3
5      State: DRAFT      State: ACCEPTED
6      Date: 2009-06-12      Date: 2009-11-26
7      Drivers: Raphael Hertzog <hertzog@debian.org>      Drivers: Raphael Hertzog <hertzog@debian.org>
8      URL: http://dep.debian.net/deps/dep3      URL: http://dep.debian.net/deps/dep3
9      Abstract:      Abstract:
# Line 31  information about them (their origin/aut Line 31  information about them (their origin/aut
31  upstream, if they are meant to be debian specific or not, etc.). Thus the  upstream, if they are meant to be debian specific or not, etc.). Thus the
32  first step is to include those information in the patches when they are  first step is to include those information in the patches when they are
33  available so that tools like the [Patch Tracking  available so that tools like the [Patch Tracking
34  System](http://patch-tracking.debian.net) can display them.  System](http://patch-tracker.debian.org) can display them.
35    
36  Scope and application  Scope and application
37  ---------------------  ---------------------
# Line 47  information. Line 47  information.
47    
48  Structure  Structure
49  ---------  ---------
50  The meta-information would be stored in a set of RFC-2822 compliant  
51  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
52  having stripped whitespace characters at the start and end of lines).  RFC-2822-like fields. (The difference with RFC 2822 is that newlines
53    are meaningful in the Description field, they are not simple
54    continuation characters). The first header should start on the first
55    non-empty line (after having stripped whitespace characters at the
56    start and end of lines).
57    
58  For patch-systems like dpatch that require the patch to be a standalone  For patch-systems like dpatch that require the patch to be a standalone
59  script, the shebang line is ignored and it is possible to put those fields  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
63  they start with a space once "`#` " (hash followed by a space) has been  they start with a space once "`#` " (hash followed by a space) has been
64  stripped from the beginning.  stripped from the beginning.
65    
66  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
67  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
68  structured content.  description (see detailed explanations of the field). A second header
69    (the “pseudo-header”) can start on any new paragraph. A line
70    containing 3 dashes (`---`) should stop the parsing: lines after it are
71    not relevant part of the meta-information.
72    
73  Any parser that expect those fields in patch headers should also  Any parser that expect those fields in patch headers should also
74  accept non-structured content and simply consider the whole content  accept non-structured content and simply append the non-structured
75  to be the value of the `Description` field.  content to the value of the `Description` field.
76    
77    All the meta-information must be UTF-8 encoded. When the patch itself
78    contains non-UTF-8 characters, it's recommended to stick to ASCII for the
79    meta-information.
80    
81  Standard fields  Standard fields
82  ---------------  ---------------
83    
84  In the following section, `<Vendor>` can be "Debian" or the name  In the following section, `<Vendor>` can be "Debian" or the name
85  of any other distribution that tracks the same problem/patch.  of any other distribution that tracks the same problem/patch. Vendor
86    names are case-insensitive ("Fedora" and "fedora" refer to the same
87    vendor).
88    
89    * `Description` (required)    * `Description` or `Subject` (required)
90    
91      This obligatory field contains at least a short description on the      This obligatory field contains at least a short description on the
92      first line. Supplementary lines can be used to provide a longer      first line. When `Subject` is used, it is expected that the long
93        description is outside of the structured fields. With `Description` it
94        is possible to embed them in the field using continuation lines.
95    
96        In both cases, the long description allows for a more verbose
97      explanation of the patch and its history.      explanation of the patch and its history.
98    
99      This field should explain why the patch is vendor-specicific (ex:      This field should explain why the patch is vendor-specicific (ex:
# Line 84  of any other distribution that tracks th Line 101  of any other distribution that tracks th
101      upstream but has been rejected, the description should also document      upstream but has been rejected, the description should also document
102      why it's kept and what were the reasons for the reject.      why it's kept and what were the reasons for the reject.
103    
104    * `Origin` (required)      It's recommended to keep each line shorter than 80 characters.
105    
106      * `Origin` (required except if `Author` is present)
107    
108      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
109      single keyword that can have the following standard values: "upstream"      should be a simple URL. For patches backported/taken from upstream, it
110      (in the case of a patch cherry-picked from the upstream VCS),      should point into the upstream VCS web interface when possible,
111      "backport" (in the case of an upstream patch that had to be modified      otherwise it can simply list the relevant commit identifier (it should
112      to apply on the current version), "vendor" for a patch created      be prefixed with "commit:" in that case). For other cases, one should
113      by Debian or another distribution vendor, or "other" for all other      simply indicate the URL where the patch was taken from (mailing list
114      kind of patches. It can be optionally followed by a colon with      archives, distribution bugtrackers, etc.) when possible.
115      leading/trailing spaces before/after it. In that case, all the content  
116      after the colon contains supplementary information defining in more      The field can be optionaly prefixed with a single keyword followed by
117      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
118      URL. For patches backported/taken from upstream, it should point into      "upstream" (in the case of a patch cherry-picked from the upstream
119      the upstream VCS web interface when possible, otherwise it can simply      VCS), "backport" (in the case of an upstream patch that had to be
120      list the relevant commit identifier (it should be prefixed with      modified to apply on the current version), "vendor" for a patch
121      "commit:" in that case). For other cases, one should simply indicate      created by Debian or another distribution vendor, or "other" for all
122      the URL where the patch got grabbed (mailing list archives,      other kind of patches.
     distribution bugtrackers, etc.) when possible.  
123    
124      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
125      as "other". When copying a patch from another vendor, the      categorized as "other". When copying a patch from another vendor, the
126      meta-information (and hence this field) should be kept if present, or      meta-information (and hence this field) should be kept if present, or
127      created if necessary with a "vendor" origin.      created if necessary with a "vendor" origin.
128    
129        If the `Author` field is present, the `Origin` field can be omitted
130        and it's assumed that the patch comes from its author.
131    
132    * `Bug-<Vendor>` or `Bug` (optional)    * `Bug-<Vendor>` or `Bug` (optional)
133    
134      It contains one URL pointing to the related bug (possibly fixed by the      It contains one URL pointing to the related bug (possibly fixed by the
# Line 115  of any other distribution that tracks th Line 136  of any other distribution that tracks th
136      bug tracker. Those fields can be used multiple times if several      bug tracker. Those fields can be used multiple times if several
137      bugs are concerned.      bugs are concerned.
138    
139        The vendor name is explicitely encoded in the field name so that
140        vendors can share patches among them without having to update the
141        meta-information in most cases. The upstream bug URL is special
142        cased because it's the central point of cooperation and it must
143        be easily distinguishable among all the bug URLs.
144    
145    * `Forwarded` (optional)    * `Forwarded` (optional)
146    
147      Any value other than "no" or "not-needed" means that the patch      Any value other than "no" or "not-needed" means that the patch
# Line 128  of any other distribution that tracks th Line 155  of any other distribution that tracks th
155      be "not-needed" to indicate that the patch must not be forwarded      be "not-needed" to indicate that the patch must not be forwarded
156      upstream (whereas "no" simply means that it has not yet been done).      upstream (whereas "no" simply means that it has not yet been done).
157    
158    * `Author` (optional)    * `Author` or `From` (optional)
159    
160      This field can be used to record the name and email of the patch author      This field can be used to record the name and email of the patch author
161      (ex: "`John Bear <foo@bar.net>`"). Its usage is recommended when the      (ex: "`John Bear <foo@example.com>`"). Its usage is recommended when the
162      patch author did not add copyright notices for his work in the patch      patch author did not add copyright notices for his work in the patch
163      itself. It's also a good idea to add this contact information when      itself. It's also a good idea to add this contact information when
164      the patch needs to be maintained over time because it has very little      the patch needs to be maintained over time because it has very little
165      chance of being integrated upstream.      chance of being integrated upstream. This field can be used multiple
166        times if several people authored the patch.
167    
168    * `Reviewed-by` (optional)    * `Reviewed-by` or `Acked-by` (optional)
169    
170      This field can be used to document the fact that the patch has been      This field can be used to document the fact that the patch has been
171      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
172      format (similar to the example given for the `Author` field). This      the standard format (similar to the example given for the `Author`
173      field can be used mutiple times if several persons reviewed the      field). This field can be used multiple times if several people
174      patch.      reviewed the patch.
175    
176    * `Last-Update` (optional)    * `Last-Update` (optional)
177    
178      This field can be used to record the date when the meta-information      This field can be used to record the date when the meta-information
179      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`.  
180    
181      * `Applied-Upstream` (optional)
182    
183        This field can be used to document the fact that the patch has been
184        applied upstream. It may contain the upstream version expected to
185        contain this patch, or the URL or commit identifier of the upstream
186        commit (with commit identifiers prefixed with "commit:", as in the
187        `Origin` field), or both separated by a comma and a space.
188    
189    Sample DEP-3 compliant headers
190    ------------------------------
191    
192    A patch cherry-picked from upstream:
193    
194        From: Ulrich Drepper <drepper@redhat.com>
195        Subject: Fix regex problems with some multi-bytes characters
196    
197        * posix/bug-regex17.c: Add testcases.
198        * posix/regcomp.c (re_compile_fastmap_iter): Rewrite COMPLEX_BRACKET
199          handling.
200    
201        Origin: upstream, http://sourceware.org/git/?p=glibc.git;a=commitdiff;h=bdb56bac
202        Bug: http://sourceware.org/bugzilla/show_bug.cgi?id=9697
203        Bug-Debian: http://bugs.debian.org/510219
204    
205    A patch created by the Debian maintainer John Doe, which got forwarded
206    and rejected:
207    
208        Description: Use FHS compliant paths by default
209         Upstream is not interested in switching to those paths.
210         .
211         But we will continue using them in Debian nevertheless to comply with
212         our policy.
213        Forwarded: http://lists.example.com/oct-2006/1234.html
214        Author: John Doe <johndoe-guest@users.alioth.debian.org>
215        Last-Update: 2006-12-21
216    
217    A vendor specific patch not meant for upstream submitted on
218    the BTS by a Debian developer:
219    
220        Description: Workaround for broken symbol resolving on mips/mipsel
221         The correct fix will be done in etch and it will require toolchain
222         fixes.
223        Forwarded: not-needed
224        Origin: vendor, http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=80;bug=265678
225        Bug-Debian: http://bugs.debian.org/265678
226        Author: Thiemo Seufer <ths@debian.org>
227    
228    A patch submitted and applied upstream:
229    
230        Description: Fix widget frobnication speeds
231         Frobnicating widgets too quickly tended to cause explosions.
232        Forwarded: http://lists.example.com/2010/03/1234.html
233        Author: John Doe <johndoe-guest@users.alioth.debian.org>
234        Applied-Upstream: 1.2, http://bzr.example.com/frobnicator/trunk/revision/123
235        Last-Update: 2010-03-29
236    
237  Related links  Related links
238  -------------  -------------
# Line 164  Changes Line 246  Changes
246  * 2009-06-19: Replace Origin/Status/Patch with Origin/Forwarded. Add new  * 2009-06-19: Replace Origin/Status/Patch with Origin/Forwarded. Add new
247    fields Author and Last-Update. Rename Signed-off-by in Reviewed-by.    fields Author and Last-Update. Rename Signed-off-by in Reviewed-by.
248    Add a paragraph about the scope of the proposal.    Add a paragraph about the scope of the proposal.
249    * 2009-07-15: Make categorization in Origin optional. Make Origin optional
250      if Author is present.
251    * 2009-08-24: Add samples and mention difference with RFC-2822 related to
252      the Description field.
253    * 2009-09-07: Move to CANDIDATE status.
254    * 2009-09-26: Modified structure to allow for 2 set of fields (the header and
255      pseudo-header). Make Subject an alias of Description, From an alias of
256      Author and Acked-by an alias of Reviewed-by. All those changes allow for
257      a better compatibility with patches that are VCS changesets embedded in
258      mails (notably those generated by git format-patch).
259    * 2009-10-05: Clarify the distinction between header and field, by the
260      precedent set in RFC 2822.
261    * 2009-11-09: Clarify how non-structured paragraph are merged in the
262      Description. Make it explicit that Reviewed-by and Acked-by imply
263      approval of the change.
264    * 2009-11-26: Enforce UTF-8 usage for the meta-information and recommend
265      ASCII when the patch contains non-UTF-8 characters.
266    * 2010-04-16: Add the Applied-Upstream field.
267    * 2012-01-16: Move to ACCEPTED status.
Legend:
Removed from v.69  
changed lines
  Added in v.246
  ViewVC Help
Powered by ViewVC 1.1.5