web/deps/dep3.mdwn

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

    Title: Patch Tagging Guidelines
    DEP: 3
    State: DRAFT
    Date: 2009-06-12
    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-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
fields. 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;" (hash followed by two spaces) so that
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.

  * `Description` (required)

    This obligatory field contains at least a short description on the
    first line. Supplementary lines can be used to provide a longer
    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.

  * `Origin` (required)

    This field should document the origin of the patch. It starts with a
    single keyword that can have the following standard values: "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. 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.

    In general, a user-created patch grabbed in a BTS should be tagged
    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.

  * `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.

  * `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` (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
    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.

  * `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
    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
    `YYYY-MM-DD`.


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.
1	hertzog	60	[[meta title="DEP-3: Patch Tagging Guidelines"]]
2
3	hertzog	61	Title: Patch Tagging Guidelines
4	hertzog	60	DEP: 3
5			State: DRAFT
6			Date: 2009-06-12
7			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			System](http://patch-tracking.debian.net) 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			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
52			having stripped whitespace characters at the start and end of lines).
53
54			For patch-systems like dpatch that require the patch to be a standalone
55			script, the shebang line is ignored and it is possible to put those fields
56	hertzog	61	in comments. The line should then follow the format "`# <field>`". For
57	hertzog	63	multi-line fields, the subsequent lines should start with
58	hertzog	67	"`#`  " (hash followed by two spaces) so that
59			they start with a space once "`#` " (hash followed by a space) has been
60	hertzog	63	stripped from the beginning.
61	hertzog	60
62	hertzog	64	The set of fields ends on the first empty line. Free-form comments can
63			follow and be used for any other information that does not fit in the
64			structured content.
65	hertzog	60
66	hertzog	69	Any parser that expect those fields in patch headers should also
67			accept non-structured content and simply consider the whole content
68			to be the value of the `Description` field.
69
70	hertzog	60	Standard fields
71			---------------
72
73	hertzog	61	In the following section, `<Vendor>` can be "Debian" or the name
74	hertzog	60	of any other distribution that tracks the same problem/patch.
75
76	hertzog	61	* `Description` (required)
77	hertzog	63
78	hertzog	60	This obligatory field contains at least a short description on the
79			first line. Supplementary lines can be used to provide a longer
80	hertzog	65	explanation of the patch and its history.
81	hertzog	63
82	hertzog	65	This field should explain why the patch is vendor-specicific (ex:
83			branding patch) when that is the case. If the patch has been submitted
84			upstream but has been rejected, the description should also document
85			why it's kept and what were the reasons for the reject.
86
87	hertzog	61	* `Origin` (required)
88	hertzog	63
89	hertzog	65	This field should document the origin of the patch. It starts with a
90			single keyword that can have the following standard values: "upstream"
91			(in the case of a patch cherry-picked from the upstream VCS),
92			"backport" (in the case of an upstream patch that had to be modified
93			to apply on the current version), "vendor" for a patch created
94			by Debian or another distribution vendor, or "other" for all other
95			kind of patches. It can be optionally followed by a colon with
96			leading/trailing spaces before/after it. In that case, all the content
97			after the colon contains supplementary information defining in more
98			details the origin of the patch. In most cases, it should be a simple
99			URL. For patches backported/taken from upstream, it should point into
100			the upstream VCS web interface when possible, otherwise it can simply
101			list the relevant commit identifier (it should be prefixed with
102			"commit:" in that case). For other cases, one should simply indicate
103			the URL where the patch got grabbed (mailing list archives,
104			distribution bugtrackers, etc.) when possible.
105	hertzog	63
106	hertzog	68	In general, a user-created patch grabbed in a BTS should be tagged
107			as "other". When copying a patch from another vendor, the
108			meta-information (and hence this field) should be kept if present, or
109			created if necessary with a "vendor" origin.
110
111	hertzog	61	* `Bug-<Vendor>` or `Bug` (optional)
112	hertzog	63
113	hertzog	65	It contains one URL pointing to the related bug (possibly fixed by the
114			patch). The `Bug` field is reserved for the bug URL in the upstream
115			bug tracker. Those fields can be used multiple times if several
116			bugs are concerned.
117	hertzog	63
118	hertzog	65	* `Forwarded` (optional)
119	hertzog	63
120	hertzog	65	Any value other than "no" or "not-needed" means that the patch
121			has been forwarded upstream. Ideally the value is an URL proving
122			that it has been forwarded and where one can find more information
123			about its inclusion status.
124	hertzog	63
125	hertzog	65	If the field is missing, its implicit value is "yes" if the "Bug"
126			field is present, otherwise it's "no". The field is really required
127			only if the patch is vendor specific, in that case its value should
128			be "not-needed" to indicate that the patch must not be forwarded
129			upstream (whereas "no" simply means that it has not yet been done).
130	hertzog	63
131	hertzog	65	* `Author` (optional)
132	hertzog	63
133	hertzog	65	This field can be used to record the name and email of the patch author
134			(ex: "`John Bear <foo@bar.net>`"). Its usage is recommended when the
135			patch author did not add copyright notices for his work in the patch
136			itself. It's also a good idea to add this contact information when
137			the patch needs to be maintained over time because it has very little
138			chance of being integrated upstream.
139	hertzog	63
140	hertzog	65	* `Reviewed-by` (optional)
141	hertzog	63
142			This field can be used to document the fact that the patch has been
143	hertzog	65	reviewed by someone. It should list her name and email in the standard
144			format (similar to the example given for the `Author` field). This
145			field can be used mutiple times if several persons reviewed the
146			patch.
147	hertzog	60
148	hertzog	65	* `Last-Update` (optional)
149	hertzog	63
150	hertzog	65	This field can be used to record the date when the meta-information
151			have been last updated. It should use the ISO date format
152			`YYYY-MM-DD`.
153	hertzog	60
154
155	hertzog	62	Related links
156			-------------
157
158	hertzog	63	* [Ubuntu's patch tagging guidelines](https://wiki.ubuntu.com/UbuntuDevelopment/PatchTaggingGuidelines)
159	hertzog	62
160	hertzog	60	Changes
161			-------
162
163			* 2009-06-12: Initial draft by Raphaël Hertzog.
164	hertzog	65	* 2009-06-19: Replace Origin/Status/Patch with Origin/Forwarded. Add new
165			fields Author and Last-Update. Rename Signed-off-by in Reviewed-by.
166	hertzog	66	Add a paragraph about the scope of the proposal.