web/deps/dep3.mdwn

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

    Title: Patch Tagging Guidelines
    DEP: 3
    State: CANDIDATE
    Date: 2009-11-26
    Drivers: Raphael Hertzog <hertzog@debian.org>
    URL: http://dep.debian.net/deps/dep3
    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`.

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

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