| 1 |
[[meta title="DEP-3: Patch Tagging Guidelines"]]
|
| 2 |
|
| 3 |
Title: Patch Tagging Guidelines
|
| 4 |
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 |
available so that tools like the [Patch Tracking
|
| 34 |
System](http://patch-tracking.debian.net) 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 |
The meta-information would be stored in a set of RFC-2822 compliant
|
| 51 |
fields. Those fields should start on the first non-empty line (after
|
| 52 |
having stripped whitespace characters at the start and end of lines).
|
| 53 |
|
| 54 |
For patch-systems like dpatch that require the patch to be a standalone
|
| 55 |
script, the shebang line is ignored and it is possible to put those fields
|
| 56 |
in comments. The line should then follow the format "`# <field>`". For
|
| 57 |
multi-line fields, the subsequent lines should start with
|
| 58 |
"`#` " (hash followed by two spaces) so that
|
| 59 |
they start with a space once "`#` " (hash followed by a space) has been
|
| 60 |
stripped from the beginning.
|
| 61 |
|
| 62 |
The set of fields ends on the first empty line. Free-form comments can
|
| 63 |
follow and be used for any other information that does not fit in the
|
| 64 |
structured content.
|
| 65 |
|
| 66 |
Standard fields
|
| 67 |
---------------
|
| 68 |
|
| 69 |
In the following section, `<Vendor>` can be "Debian" or the name
|
| 70 |
of any other distribution that tracks the same problem/patch.
|
| 71 |
|
| 72 |
* `Description` (required)
|
| 73 |
|
| 74 |
This obligatory field contains at least a short description on the
|
| 75 |
first line. Supplementary lines can be used to provide a longer
|
| 76 |
explanation of the patch and its history.
|
| 77 |
|
| 78 |
This field should explain why the patch is vendor-specicific (ex:
|
| 79 |
branding patch) when that is the case. If the patch has been submitted
|
| 80 |
upstream but has been rejected, the description should also document
|
| 81 |
why it's kept and what were the reasons for the reject.
|
| 82 |
|
| 83 |
* `Origin` (required)
|
| 84 |
|
| 85 |
This field should document the origin of the patch. It starts with a
|
| 86 |
single keyword that can have the following standard values: "upstream"
|
| 87 |
(in the case of a patch cherry-picked from the upstream VCS),
|
| 88 |
"backport" (in the case of an upstream patch that had to be modified
|
| 89 |
to apply on the current version), "vendor" for a patch created
|
| 90 |
by Debian or another distribution vendor, or "other" for all other
|
| 91 |
kind of patches. It can be optionally followed by a colon with
|
| 92 |
leading/trailing spaces before/after it. In that case, all the content
|
| 93 |
after the colon contains supplementary information defining in more
|
| 94 |
details the origin of the patch. In most cases, it should be a simple
|
| 95 |
URL. For patches backported/taken from upstream, it should point into
|
| 96 |
the upstream VCS web interface when possible, otherwise it can simply
|
| 97 |
list the relevant commit identifier (it should be prefixed with
|
| 98 |
"commit:" in that case). For other cases, one should simply indicate
|
| 99 |
the URL where the patch got grabbed (mailing list archives,
|
| 100 |
distribution bugtrackers, etc.) when possible.
|
| 101 |
|
| 102 |
* `Bug-<Vendor>` or `Bug` (optional)
|
| 103 |
|
| 104 |
It contains one URL pointing to the related bug (possibly fixed by the
|
| 105 |
patch). The `Bug` field is reserved for the bug URL in the upstream
|
| 106 |
bug tracker. Those fields can be used multiple times if several
|
| 107 |
bugs are concerned.
|
| 108 |
|
| 109 |
* `Forwarded` (optional)
|
| 110 |
|
| 111 |
Any value other than "no" or "not-needed" means that the patch
|
| 112 |
has been forwarded upstream. Ideally the value is an URL proving
|
| 113 |
that it has been forwarded and where one can find more information
|
| 114 |
about its inclusion status.
|
| 115 |
|
| 116 |
If the field is missing, its implicit value is "yes" if the "Bug"
|
| 117 |
field is present, otherwise it's "no". The field is really required
|
| 118 |
only if the patch is vendor specific, in that case its value should
|
| 119 |
be "not-needed" to indicate that the patch must not be forwarded
|
| 120 |
upstream (whereas "no" simply means that it has not yet been done).
|
| 121 |
|
| 122 |
* `Author` (optional)
|
| 123 |
|
| 124 |
This field can be used to record the name and email of the patch author
|
| 125 |
(ex: "`John Bear <foo@bar.net>`"). Its usage is recommended when the
|
| 126 |
patch author did not add copyright notices for his work in the patch
|
| 127 |
itself. It's also a good idea to add this contact information when
|
| 128 |
the patch needs to be maintained over time because it has very little
|
| 129 |
chance of being integrated upstream.
|
| 130 |
|
| 131 |
* `Reviewed-by` (optional)
|
| 132 |
|
| 133 |
This field can be used to document the fact that the patch has been
|
| 134 |
reviewed by someone. It should list her name and email in the standard
|
| 135 |
format (similar to the example given for the `Author` field). This
|
| 136 |
field can be used mutiple times if several persons reviewed the
|
| 137 |
patch.
|
| 138 |
|
| 139 |
* `Last-Update` (optional)
|
| 140 |
|
| 141 |
This field can be used to record the date when the meta-information
|
| 142 |
have been last updated. It should use the ISO date format
|
| 143 |
`YYYY-MM-DD`.
|
| 144 |
|
| 145 |
|
| 146 |
Related links
|
| 147 |
-------------
|
| 148 |
|
| 149 |
* [Ubuntu's patch tagging guidelines](https://wiki.ubuntu.com/UbuntuDevelopment/PatchTaggingGuidelines)
|
| 150 |
|
| 151 |
Changes
|
| 152 |
-------
|
| 153 |
|
| 154 |
* 2009-06-12: Initial draft by Raphaël Hertzog.
|
| 155 |
* 2009-06-19: Replace Origin/Status/Patch with Origin/Forwarded. Add new
|
| 156 |
fields Author and Last-Update. Rename Signed-off-by in Reviewed-by.
|
| 157 |
Add a paragraph about the scope of the proposal.
|
Parent Directory
| 
Revision Log