web/deps/dep3.mdwn

[[!meta title="DEP-3: Patch Tagging Guidelines"]]

    Title: Patch Tagging Guidelines
    DEP: 3
    State: ACCEPTED
    Date: 2009-11-26
    Drivers: Raphael Hertzog <hertzog@debian.org>
    URL: http://dep.debian.net/deps/dep3
    Source: http://anonscm.debian.org/viewvc/dep/web/deps/dep3.mdwn
    Abstract:
     Meta-information embedded in patches applied to Debian
     packages


Introduction
------------

This is a proposal to formalize a set of meta-information
to be embedded in patches applied to Debian packages. Most
patch systems allow for a free-from description preceeding
the content of the patch and the plan is to make use of that
space to embed some structured content.


Motivation
----------

In order to ensure high-quality in the distribution, it's important to
facilitate the review of patches that are applied to Debian packages. To
achieve this task we must be able to browse the patches and discover some
information about them (their origin/author, if they have been forwarded
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-tracker.debian.org) 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 one or two headers: sets 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). 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
in comments. The line should then follow the format "`# <field>`". For
multi-line fields, the subsequent lines should start with
"`#`&nbsp;&nbsp;" (hash followed by two spaces) so that
they start with a space once "`#` " (hash followed by a space) has been
stripped from the beginning.

A header always ends 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 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 append the non-structured
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
---------------

In the following section, `<Vendor>` can be "Debian" or the name
of any other distribution that tracks the same problem/patch. Vendor
names are case-insensitive ("Fedora" and "fedora" refer to the same
vendor).

  * `Description` or `Subject` (required)

    This obligatory field contains at least a short description on the
    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:
    branding patch) when that is the case. If the patch has been submitted
    upstream but has been rejected, the description should also document
    why it's kept and what were the reasons for the reject.

    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.

    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
    patch). The `Bug` field is reserved for the bug URL in the upstream
    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
    has been forwarded upstream. Ideally the value is an URL proving
    that it has been forwarded and where one can find more information
    about its inclusion status.

    If the field is missing, its implicit value is "yes" if the "Bug"
    field is present, otherwise it's "no". The field is really required
    only if the patch is vendor specific, in that case its value should
    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` or `From` (optional)

    This field can be used to record the name and email of the patch author
    (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` or `Acked-by` (optional)

    This field can be used to document the fact that the patch has been
    reviewed and approved 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 multiple times if several people
    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:

    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>

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
-------------

  * [Ubuntu's patch tagging guidelines](https://wiki.ubuntu.com/UbuntuDevelopment/PatchTaggingGuidelines)

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