Title: Patch Tagging Guidelines DEP: 3 State: CANDIDATE Date: 2009-11-26 Drivers: Raphael Hertzog <email@example.com> URL: http://dep.debian.net/deps/dep3 Abstract: Meta-information embedded in patches applied to Debian packages
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.
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 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.
The meta-information would be stored in one or two headers: sets of RFC-2822-like fields. (The difference with RFC 2822 is that newlines are meaningful in the Description field, they are not simple continuation characters). The first header 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
# ” (hash followed by two spaces) so that
they start with a space once “
# ” (hash followed by a space) has been
stripped from the beginning.
A header always ends on the first empty line. Free-form comments can
follow and should be considered as supplementary lines of the long
description (see detailed explanations of the field). A second header
(the “pseudo-header”) can start on any new paragraph. A line
containing 3 dashes (
---) should stop the parsing: lines after it are
not relevant part of the meta-information.
Any parser that expect those fields in patch headers should also
accept non-structured content and simply append the non-structured
content to the value of the
All the meta-information must be UTF-8 encoded. When the patch itself contains non-UTF-8 characters, it’s recommended to stick to ASCII for the meta-information.
In the following section,
<Vendor> can be “Debian” or the name
of any other distribution that tracks the same problem/patch. Vendor
names are case-insensitive (“Fedora” and “fedora” refer to the same
This obligatory field contains at least a short description on the first line. When
Subjectis used, it is expected that the long description is outside of the structured fields. With
Descriptionit is possible to embed them in the field using continuation lines.
In both cases, the long description allows for a more verbose 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.
It’s recommended to keep each line shorter than 80 characters.
Origin(required except if
This field should document 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 was taken from (mailing list archives, distribution bugtrackers, etc.) when possible.
The field can be optionaly prefixed with a single keyword followed by a comma and a space to categorize the origin. The allowed keywords are “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.
In general, a user-created patch grabbed in a BTS should be categorized 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.
Authorfield is present, the
Originfield can be omitted and it’s assumed that the patch comes from its author.
It contains one URL pointing to the related bug (possibly fixed by the patch). The
Bugfield is reserved for the bug URL in the upstream bug tracker. Those fields can be used multiple times if several bugs are concerned.
The vendor name is explicitely encoded in the field name so that vendors can share patches among them without having to update the meta-information in most cases. The upstream bug URL is special cased because it’s the central point of cooperation and it must be easily distinguishable among all the bug URLs.
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).
This field can be used to record the name and email of the patch author (ex: “
John Bear <firstname.lastname@example.org>”). 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. This field can be used multiple times if several people authored the patch.
This field can be used to document the fact that the patch has been reviewed and approved by someone. It should list her name and email in the standard format (similar to the example given for the
Authorfield). This field can be used multiple times if several people reviewed the patch.
This field can be used to record the date when the meta-information was last updated. It should use the ISO date format
This field can be used to document the fact that the patch has been applied upstream. It may contain the upstream version expected to contain this patch, or the URL or commit identifier of the upstream commit (with commit identifiers prefixed with “commit:”, as in the
Originfield), or both separated by a comma and a space.
Sample DEP-3 compliant headers
A patch cherry-picked from upstream:
From: Ulrich Drepper <email@example.com> Subject: Fix regex problems with some multi-bytes characters * posix/bug-regex17.c: Add testcases. * posix/regcomp.c (re_compile_fastmap_iter): Rewrite COMPLEX_BRACKET handling. Origin: upstream, http://sourceware.org/git/?p=glibc.git;a=commitdiff;h=bdb56bac Bug: http://sourceware.org/bugzilla/show_bug.cgi?id=9697 Bug-Debian: http://bugs.debian.org/510219
A patch created by the Debian maintainer John Doe, which got forwarded and rejected:
Description: Use FHS compliant paths by default Upstream is not interested in switching to those paths. . But we will continue using them in Debian nevertheless to comply with our policy. Forwarded: http://lists.example.com/oct-2006/1234.html Author: John Doe <firstname.lastname@example.org> Last-Update: 2006-12-21
A vendor specific patch not meant for upstream submitted on the BTS by a Debian developer:
Description: Workaround for broken symbol resolving on mips/mipsel The correct fix will be done in etch and it will require toolchain fixes. Forwarded: not-needed Origin: vendor, http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=80;bug=265678 Bug-Debian: http://bugs.debian.org/265678 Author: Thiemo Seufer <email@example.com>
A patch submitted and applied upstream:
Description: Fix widget frobnication speeds Frobnicating widgets too quickly tended to cause explosions. Forwarded: http://lists.example.com/2010/03/1234.html Author: John Doe <firstname.lastname@example.org> Applied-Upstream: 1.2, http://bzr.example.com/frobnicator/trunk/revision/123 Last-Update: 2010-03-29
- 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.
- 2009-07-15: Make categorization in Origin optional. Make Origin optional if Author is present.
- 2009-08-24: Add samples and mention difference with RFC-2822 related to the Description field.
- 2009-09-07: Move to CANDIDATE status.
- 2009-09-26: Modified structure to allow for 2 set of fields (the header and pseudo-header). Make Subject an alias of Description, From an alias of Author and Acked-by an alias of Reviewed-by. All those changes allow for a better compatibility with patches that are VCS changesets embedded in mails (notably those generated by git format-patch).
- 2009-10-05: Clarify the distinction between header and field, by the precedent set in RFC 2822.
- 2009-11-09: Clarify how non-structured paragraph are merged in the Description. Make it explicit that Reviewed-by and Acked-by imply approval of the change.
- 2009-11-26: Enforce UTF-8 usage for the meta-information and recommend ASCII when the patch contains non-UTF-8 characters.
- 2010-04-16: Add the Applied-Upstream field.