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.

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