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.


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;" (dash followed by two spaces) so that
they start with a space once "`#` " (dash followed by a space) has been
stripped from the beginning.


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.

  * `Origin` (required)

    This field should document the origin of the patch. It 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). Any other
    value is supposed to be free-form text describing the origin of the
    patch. It should typically be the name and email of the patch author
    (ex: "`John Bear <foo@bar.net>`") or the project/company that she worked
    for when she authored the patch.

  * `Bug-<Vendor>` or `Bug` (optional)

    It contains one or more URLs (space separated) pointing to the related bugs
    (possibly fixed by the patch). The `Bug` field is reserved
    for the bug URL(s) in the upstream bug tracker.

  * `Patch` (optional)

    URL pointing to the patch. It can be in a VCS web interface,
    a BTS attachment, etc. If the patch is available in the upstream VCS
    or BTS, those URLs take precedence.

  * `Commit` (optional)

    One or more commit identifiers. This should only be used when the
    `Patch` field can't be used because the upstream project has no VCS web
    interface or similar restrictions.

  * `Status` (optional)

    This field is a textual explanation of its status concerning its
    inclusion in the upstream project. The first line should consist of a
    single keyword among "&lt;vendor&gt;-specific" (the patch must not be
    forwarded as it is specific to a vendor, ex: branding patches), 
    "must-be-forwarded" (nobody has taken the time to forward the patch
    yet), "forwarded" (the patch has been forwarded, the Bug or Patch
    fields should contain the corresponding URLs) or "rejected" (the patch
    has been submitted but it has been rejected upstream). Supplementary
    lines can be used to explain in more details the status of the patch.
    It should be used for example to explain why the patch has been
    rejected, or why this change is only meaningful for the vendor.

  * `Signed-off-by` (optional)

    This field can be used to document the fact that the patch has been
    reviewed by one or more persons. It should list their names and
    emails in the standard format (similar to the example given for
    the `Origin` field), separated by commas if needed.


Interpretation
--------------

In the analysis of the meta-information, a certain number of related
facts can be deduced from the absence, presence, or combinations of fields
and their values.

  * Has the patch been forwarded upstream?

    If there is a `Status` field, its value answers the question.
    If there's an `Origin` field and it contains "upstream" or "backport",
    the patch comes from upstream and it doesn't need to be forwarded.
    The same is true if there's a `Commit` field.
    In other cases, if there is a `Bug` field, then the patch has most
    likely been referenced in the bug and upstream should know about it.
    Any package maintainer should ensure that the existence of the patch
    has been documented in the upstream bug log when he adds the
    patches' meta-information.


Related links
-------------

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

Changes
-------

* 2009-06-12: Initial draft by Raphaël Hertzog.

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
37			Structure
38			---------
39			The meta-information would be stored in a set of RFC-2822 compliant
40			fields. Those fields should start on the first non-empty line (after
41			having stripped whitespace characters at the start and end of lines).
42
43			For patch-systems like dpatch that require the patch to be a standalone
44			script, the shebang line is ignored and it is possible to put those fields
45	hertzog	61	in comments. The line should then follow the format "`# <field>`". For
46	hertzog	63	multi-line fields, the subsequent lines should start with
47			"`#`  " (dash followed by two spaces) so that
48			they start with a space once "`#` " (dash followed by a space) has been
49			stripped from the beginning.
50	hertzog	60
51
52			Standard fields
53			---------------
54
55	hertzog	61	In the following section, `<Vendor>` can be "Debian" or the name
56	hertzog	60	of any other distribution that tracks the same problem/patch.
57
58	hertzog	61	* `Description` (required)
59	hertzog	63
60	hertzog	60	This obligatory field contains at least a short description on the
61			first line. Supplementary lines can be used to provide a longer
62			explanation of the patch.
63	hertzog	63
64	hertzog	61	* `Origin` (required)
65	hertzog	63
66	hertzog	60	This field should document the origin of the patch. It can have the
67			following standard values: "upstream" (in the case of a patch cherry-picked
68			from the upstream VCS), "backport" (in the case of an upstream patch
69			that had to be modified to apply on the current version). Any other
70			value is supposed to be free-form text describing the origin of the
71			patch. It should typically be the name and email of the patch author
72	hertzog	61	(ex: "`John Bear <foo@bar.net>`") or the project/company that she worked
73	hertzog	60	for when she authored the patch.
74	hertzog	63
75	hertzog	61	* `Bug-<Vendor>` or `Bug` (optional)
76	hertzog	63
77	hertzog	60	It contains one or more URLs (space separated) pointing to the related bugs
78	hertzog	61	(possibly fixed by the patch). The `Bug` field is reserved
79	hertzog	60	for the bug URL(s) in the upstream bug tracker.
80	hertzog	63
81	hertzog	61	* `Patch` (optional)
82	hertzog	63
83	hertzog	60	URL pointing to the patch. It can be in a VCS web interface,
84			a BTS attachment, etc. If the patch is available in the upstream VCS
85			or BTS, those URLs take precedence.
86	hertzog	63
87	hertzog	61	* `Commit` (optional)
88	hertzog	63
89	hertzog	60	One or more commit identifiers. This should only be used when the
90	hertzog	61	`Patch` field can't be used because the upstream project has no VCS web
91	hertzog	60	interface or similar restrictions.
92	hertzog	63
93	hertzog	61	* `Status` (optional)
94	hertzog	63
95	hertzog	60	This field is a textual explanation of its status concerning its
96			inclusion in the upstream project. The first line should consist of a
97	hertzog	61	single keyword among "<vendor>-specific" (the patch must not be
98	hertzog	60	forwarded as it is specific to a vendor, ex: branding patches),
99			"must-be-forwarded" (nobody has taken the time to forward the patch
100			yet), "forwarded" (the patch has been forwarded, the Bug or Patch
101			fields should contain the corresponding URLs) or "rejected" (the patch
102			has been submitted but it has been rejected upstream). Supplementary
103			lines can be used to explain in more details the status of the patch.
104			It should be used for example to explain why the patch has been
105			rejected, or why this change is only meaningful for the vendor.
106	hertzog	63
107	hertzog	62	* `Signed-off-by` (optional)
108	hertzog	60
109	hertzog	63	This field can be used to document the fact that the patch has been
110			reviewed by one or more persons. It should list their names and
111			emails in the standard format (similar to the example given for
112			the `Origin` field), separated by commas if needed.
113	hertzog	60
114	hertzog	63
115	hertzog	60	Interpretation
116			--------------
117
118			In the analysis of the meta-information, a certain number of related
119			facts can be deduced from the absence, presence, or combinations of fields
120			and their values.
121
122			* Has the patch been forwarded upstream?
123	hertzog	63
124			If there is a `Status` field, its value answers the question.
125			If there's an `Origin` field and it contains "upstream" or "backport",
126	hertzog	60	the patch comes from upstream and it doesn't need to be forwarded.
127	hertzog	63	The same is true if there's a `Commit` field.
128			In other cases, if there is a `Bug` field, then the patch has most
129	hertzog	60	likely been referenced in the bug and upstream should know about it.
130			Any package maintainer should ensure that the existence of the patch
131			has been documented in the upstream bug log when he adds the
132			patches' meta-information.
133
134	hertzog	62
135			Related links
136			-------------
137
138	hertzog	63	* [Ubuntu's patch tagging guidelines](https://wiki.ubuntu.com/UbuntuDevelopment/PatchTaggingGuidelines)
139	hertzog	62
140	hertzog	60	Changes
141			-------
142
143			* 2009-06-12: Initial draft by Raphaël Hertzog.
144