| 1 |
[[meta title="DEP-3: Patch Tagging Guidelines"]]
|
| 2 |
|
| 3 |
Title: Patch Tagging Guidelines
|
| 4 |
DEP: 3
|
| 5 |
State: CANDIDATE
|
| 6 |
Date: 2009-11-26
|
| 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-tracker.debian.org) 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 |
|
| 51 |
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 |
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 |
in comments. The line should then follow the format "`# <field>`". For
|
| 61 |
multi-line fields, the subsequent lines should start with
|
| 62 |
"`#` " (hash followed by two spaces) so that
|
| 63 |
they start with a space once "`#` " (hash followed by a space) has been
|
| 64 |
stripped from the beginning.
|
| 65 |
|
| 66 |
A header always ends on the first empty line. Free-form comments can
|
| 67 |
follow and should be considered as supplementary lines of the long
|
| 68 |
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 |
|
| 73 |
Any parser that expect those fields in patch headers should also
|
| 74 |
accept non-structured content and simply append the non-structured
|
| 75 |
content to the value of the `Description` field.
|
| 76 |
|
| 77 |
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 |
Standard fields
|
| 82 |
---------------
|
| 83 |
|
| 84 |
In the following section, `<Vendor>` can be "Debian" or the name
|
| 85 |
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 |
|
| 89 |
* `Description` or `Subject` (required)
|
| 90 |
|
| 91 |
This obligatory field contains at least a short description on the
|
| 92 |
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 |
explanation of the patch and its history.
|
| 98 |
|
| 99 |
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 |
It's recommended to keep each line shorter than 80 characters.
|
| 105 |
|
| 106 |
* `Origin` (required except if `Author` is present)
|
| 107 |
|
| 108 |
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 |
|
| 116 |
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 |
meta-information (and hence this field) should be kept if present, or
|
| 127 |
created if necessary with a "vendor" origin.
|
| 128 |
|
| 129 |
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 |
* `Bug-<Vendor>` or `Bug` (optional)
|
| 133 |
|
| 134 |
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 |
|
| 139 |
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 |
* `Forwarded` (optional)
|
| 146 |
|
| 147 |
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 |
|
| 152 |
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 |
|
| 158 |
* `Author` or `From` (optional)
|
| 159 |
|
| 160 |
This field can be used to record the name and email of the patch author
|
| 161 |
(ex: "`John Bear <foo@example.com>`"). Its usage is recommended when the
|
| 162 |
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 |
chance of being integrated upstream. This field can be used multiple
|
| 166 |
times if several people authored the patch.
|
| 167 |
|
| 168 |
* `Reviewed-by` or `Acked-by` (optional)
|
| 169 |
|
| 170 |
This field can be used to document the fact that the patch has been
|
| 171 |
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 |
|
| 176 |
* `Last-Update` (optional)
|
| 177 |
|
| 178 |
This field can be used to record the date when the meta-information
|
| 179 |
was last updated. It should use the ISO date format `YYYY-MM-DD`.
|
| 180 |
|
| 181 |
Sample DEP-3 compliant headers
|
| 182 |
------------------------------
|
| 183 |
|
| 184 |
A patch cherry-picked from upstream:
|
| 185 |
|
| 186 |
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 |
Origin: upstream, http://sourceware.org/git/?p=glibc.git;a=commitdiff;h=bdb56bac
|
| 194 |
Bug: http://sourceware.org/bugzilla/show_bug.cgi?id=9697
|
| 195 |
Bug-Debian: http://bugs.debian.org/510219
|
| 196 |
|
| 197 |
A patch created by the Debian maintainer John Doe, which got forwarded
|
| 198 |
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 |
Author: John Doe <johndoe-guest@users.alioth.debian.org>
|
| 207 |
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 |
Origin: vendor, http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=80;bug=265678
|
| 217 |
Bug-Debian: http://bugs.debian.org/265678
|
| 218 |
Author: Thiemo Seufer <ths@debian.org>
|
| 219 |
|
| 220 |
Related links
|
| 221 |
-------------
|
| 222 |
|
| 223 |
* [Ubuntu's patch tagging guidelines](https://wiki.ubuntu.com/UbuntuDevelopment/PatchTaggingGuidelines)
|
| 224 |
|
| 225 |
Changes
|
| 226 |
-------
|
| 227 |
|
| 228 |
* 2009-06-12: Initial draft by Raphaël Hertzog.
|
| 229 |
* 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 |
Add a paragraph about the scope of the proposal.
|
| 232 |
* 2009-07-15: Make categorization in Origin optional. Make Origin optional
|
| 233 |
if Author is present.
|
| 234 |
* 2009-08-24: Add samples and mention difference with RFC-2822 related to
|
| 235 |
the Description field.
|
| 236 |
* 2009-09-07: Move to CANDIDATE status.
|
| 237 |
* 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 |
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 |
* 2009-10-05: Clarify the distinction between header and field, by the
|
| 243 |
precedent set in RFC 2822.
|
| 244 |
* 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 |
* 2009-11-26: Enforce UTF-8 usage for the meta-information and recommend
|
| 248 |
ASCII when the patch contains non-UTF-8 characters.
|
Parent Directory
| 
Revision Log