Title: Patch Tagging Guidelines
DEP: 3
State: ACCEPTED
Date: 2009-11-26
Drivers: Raphael Hertzog <hertzog@debian.org>
URL: http://dep.debian.net/deps/dep3
Source: https://salsa.debian.org/dep-team/deps/-/blob/master/web/deps/dep3.mdwn
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 preceding 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 Debian Package Tracker) 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 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 Description field.

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.

Standard fields

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 vendor).

Compatibility with git patches

The files produced by git format-patch are in the mailbox format, with RFC-2822 formatted fields From, Date and Subject, followed by the git commit message body, and headers terminating in ---. Such patch files can be used as-is, but in most cases appending a Bug: <url> after the git commit message will greatly help tracking the state of the patch.

A single patch can be created with e.g. git format-patch -1 d33286c from a single commit. Avoid using git show as it lacks the full headers.

In most cases it is advisable to use DEP-3 compliant helper tools such as git-buildpackage's patch queue feature (gbp pq). They will typically let you import the debian/patches contents into a dedicated branch that can be manipulated with the usual git commands, and then export it back to patch files in the correct format.

Sample DEP-3 compliant headers

A git commit downloaded from upstream by appending .patch to the GitHub url, and with "Origin:" and "Bug:" fields added manually:

From d33286c75b623cfb249c627b0c348be62e6377c9 Mon Sep 17 00:00:00 2001
From: Jaap Karssenberg <jaap.karssenberg@gmail.com>
Date: Tue, 11 Feb 2025 21:28:17 +0100
Subject: [PATCH] Fixup focus of quicknote plugin

Fixes #2764

Origin: upstream, https://github.com/zim-desktop-wiki/zim-desktop-wiki/commit/d33286c75b623cfb249c627b0c348be62e6377c9.patch
Bug: https://github.com/zim-desktop-wiki/zim-desktop-wiki/issues/2764
Bug-Debian: https://bugs.debian.org/1110423
----
 zim/plugins/quicknote.py | 4 ++++
 1 file changed, 4 insertions(+)
...

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 <johndoe-guest@users.alioth.debian.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 <ths@debian.org>

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 <johndoe-guest@users.alioth.debian.org>
Applied-Upstream: 1.2, http://bzr.example.com/frobnicator/trunk/revision/123
Last-Update: 2010-03-29

Changes