RFC: DEP-3: Patch Tagging Guidelines

To: debian-devel@lists.debian.org
Subject: RFC: DEP-3: Patch Tagging Guidelines
From: Raphael Hertzog <hertzog@debian.org>
Date: Mon, 15 Jun 2009 18:12:49 +0200
Message-id: <[🔎] 20090615161249.GA9869@rivendell>
Mail-followup-to: debian-devel@lists.debian.org

Hello,

please find below a first draft of DEP-3 that I called Patch Tagging
Guidelines. The idea is to standardize a set of meta-information to embed
in patches that we apply. Please review, share your comments and ideas of
enhancements.

If (and once) we have consensus that it is good idea to standardize those
information, we can take supplementary steps to ensure they are not
forgotten and correctly filled:
- lintian can advise using this format in quilt-patch-missing-description
or dpatch-missing-description, it can also check for correctness when
packages are trying to use of this format
- in format "3.0 (quilt)" dpkg-source would create initial headers
respecting this format automatically based on the changelog when it
creates a new patch
- fix some tools to correctly preserve those information (apparently
cdbs-edit-patch is not wise enough to do this by default)
- the developers-reference could be updated to recommend usage of this
format

The latest version of the DEP is on the web:
http://dep.debian.net/deps/dep3/

Text version follows:

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.

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.

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.