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	[[meta title="DEP-3: Patch Tagging Guidelines"]]
2
3	Title: Patch Tagging Guidelines
4	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	available so that tools like the [Patch Tracking
34	System](http://patch-tracking.debian.net) can display them.
35
36	Scope and application
37	---------------------
38
39	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	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	in comments. The line should then follow the format "`# <field>`". For
57	multi-line fields, the subsequent lines should start with
58	"`#`  " (hash followed by two spaces) so that
59	they start with a space once "`#` " (hash followed by a space) has been
60	stripped from the beginning.
61
62	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
66	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	Standard fields
71	---------------
72
73	In the following section, `<Vendor>` can be "Debian" or the name
74	of any other distribution that tracks the same problem/patch.
75
76	* `Description` (required)
77
78	This obligatory field contains at least a short description on the
79	first line. Supplementary lines can be used to provide a longer
80	explanation of the patch and its history.
81
82	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	* `Origin` (required)
88
89	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
106	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	* `Bug-<Vendor>` or `Bug` (optional)
112
113	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
118	* `Forwarded` (optional)
119
120	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
125	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
131	* `Author` (optional)
132
133	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
140	* `Reviewed-by` (optional)
141
142	This field can be used to document the fact that the patch has been
143	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
148	* `Last-Update` (optional)
149
150	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
154
155	Related links
156	-------------
157
158	* [Ubuntu's patch tagging guidelines](https://wiki.ubuntu.com/UbuntuDevelopment/PatchTaggingGuidelines)
159
160	Changes
161	-------
162
163	* 2009-06-12: Initial draft by Raphaël Hertzog.
164	* 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	Add a paragraph about the scope of the proposal.