| 47 |
|
|
| 48 |
Structure |
Structure |
| 49 |
--------- |
--------- |
| 50 |
The meta-information would be stored in a set of RFC-2822 compliant |
The meta-information would be stored in a set of RFC-2822-like |
| 51 |
fields. Those fields should start on the first non-empty line (after |
fields (the difference with RFC-2822 is that newlines are meaningful in |
| 52 |
having stripped whitespace characters at the start and end of lines). |
the Description field, they are not simple continuation characters). |
| 53 |
|
Those fields should start on the first non-empty line (after having |
| 54 |
|
stripped whitespace characters at the start and end of |
| 55 |
|
lines). |
| 56 |
|
|
| 57 |
For patch-systems like dpatch that require the patch to be a standalone |
For patch-systems like dpatch that require the patch to be a standalone |
| 58 |
script, the shebang line is ignored and it is possible to put those fields |
script, the shebang line is ignored and it is possible to put those fields |
| 66 |
follow and be used for any other information that does not fit in the |
follow and be used for any other information that does not fit in the |
| 67 |
structured content. |
structured content. |
| 68 |
|
|
| 69 |
|
Any parser that expect those fields in patch headers should also |
| 70 |
|
accept non-structured content and simply consider the whole content |
| 71 |
|
to be the value of the `Description` field. |
| 72 |
|
|
| 73 |
Standard fields |
Standard fields |
| 74 |
--------------- |
--------------- |
| 75 |
|
|
| 76 |
In the following section, `<Vendor>` can be "Debian" or the name |
In the following section, `<Vendor>` can be "Debian" or the name |
| 77 |
of any other distribution that tracks the same problem/patch. |
of any other distribution that tracks the same problem/patch. Vendor |
| 78 |
|
names are case-insensitive ("Fedora" and "fedora" refer to the same |
| 79 |
|
vendor). |
| 80 |
|
|
| 81 |
* `Description` (required) |
* `Description` (required) |
| 82 |
|
|
| 89 |
upstream but has been rejected, the description should also document |
upstream but has been rejected, the description should also document |
| 90 |
why it's kept and what were the reasons for the reject. |
why it's kept and what were the reasons for the reject. |
| 91 |
|
|
| 92 |
* `Origin` (required) |
It's recommended to keep each line shorter than 80 characters. |
| 93 |
|
|
| 94 |
|
* `Origin` (required except if `Author` is present) |
| 95 |
|
|
| 96 |
This field should document the origin of the patch. It starts with a |
This field should document the origin of the patch. In most cases, it |
| 97 |
single keyword that can have the following standard values: "upstream" |
should be a simple URL. For patches backported/taken from upstream, it |
| 98 |
(in the case of a patch cherry-picked from the upstream VCS), |
should point into the upstream VCS web interface when possible, |
| 99 |
"backport" (in the case of an upstream patch that had to be modified |
otherwise it can simply list the relevant commit identifier (it should |
| 100 |
to apply on the current version), "vendor" for a patch created |
be prefixed with "commit:" in that case). For other cases, one should |
| 101 |
by Debian or another distribution vendor, or "other" for all other |
simply indicate the URL where the patch was taken from (mailing list |
| 102 |
kind of patches. It can be optionally followed by a colon with |
archives, distribution bugtrackers, etc.) when possible. |
| 103 |
leading/trailing spaces before/after it. In that case, all the content |
|
| 104 |
after the colon contains supplementary information defining in more |
The field can be optionaly prefixed with a single keyword followed by |
| 105 |
details the origin of the patch. In most cases, it should be a simple |
a comma and a space to categorize the origin. The allowed keywords are |
| 106 |
URL. For patches backported/taken from upstream, it should point into |
"upstream" (in the case of a patch cherry-picked from the upstream |
| 107 |
the upstream VCS web interface when possible, otherwise it can simply |
VCS), "backport" (in the case of an upstream patch that had to be |
| 108 |
list the relevant commit identifier (it should be prefixed with |
modified to apply on the current version), "vendor" for a patch |
| 109 |
"commit:" in that case). For other cases, one should simply indicate |
created by Debian or another distribution vendor, or "other" for all |
| 110 |
the URL where the patch got grabbed (mailing list archives, |
other kind of patches. |
|
distribution bugtrackers, etc.) when possible. |
|
| 111 |
|
|
| 112 |
In general, a user-created patch grabbed in a BTS should be tagged |
In general, a user-created patch grabbed in a BTS should be |
| 113 |
as "other". When copying a patch from another vendor, the |
categorized as "other". When copying a patch from another vendor, the |
| 114 |
meta-information (and hence this field) should be kept if present, or |
meta-information (and hence this field) should be kept if present, or |
| 115 |
created if necessary with a "vendor" origin. |
created if necessary with a "vendor" origin. |
| 116 |
|
|
| 117 |
|
If the `Author` field is present, the `Origin` field can be omitted |
| 118 |
|
and it's assumed that the patch comes from its author. |
| 119 |
|
|
| 120 |
* `Bug-<Vendor>` or `Bug` (optional) |
* `Bug-<Vendor>` or `Bug` (optional) |
| 121 |
|
|
| 122 |
It contains one URL pointing to the related bug (possibly fixed by the |
It contains one URL pointing to the related bug (possibly fixed by the |
| 124 |
bug tracker. Those fields can be used multiple times if several |
bug tracker. Those fields can be used multiple times if several |
| 125 |
bugs are concerned. |
bugs are concerned. |
| 126 |
|
|
| 127 |
|
The vendor name is explicitely encoded in the field name so that |
| 128 |
|
vendors can share patches among them without having to update the |
| 129 |
|
meta-information in most cases. The upstream bug URL is special |
| 130 |
|
cased because it's the central point of cooperation and it must |
| 131 |
|
be easily distinguishable among all the bug URLs. |
| 132 |
|
|
| 133 |
* `Forwarded` (optional) |
* `Forwarded` (optional) |
| 134 |
|
|
| 135 |
Any value other than "no" or "not-needed" means that the patch |
Any value other than "no" or "not-needed" means that the patch |
| 150 |
patch author did not add copyright notices for his work in the patch |
patch author did not add copyright notices for his work in the patch |
| 151 |
itself. It's also a good idea to add this contact information when |
itself. It's also a good idea to add this contact information when |
| 152 |
the patch needs to be maintained over time because it has very little |
the patch needs to be maintained over time because it has very little |
| 153 |
chance of being integrated upstream. |
chance of being integrated upstream. This field can be used multiple |
| 154 |
|
times if several people authored the patch. |
| 155 |
|
|
| 156 |
* `Reviewed-by` (optional) |
* `Reviewed-by` (optional) |
| 157 |
|
|
| 158 |
This field can be used to document the fact that the patch has been |
This field can be used to document the fact that the patch has been |
| 159 |
reviewed by someone. It should list her name and email in the standard |
reviewed by someone. It should list her name and email in the standard |
| 160 |
format (similar to the example given for the `Author` field). This |
format (similar to the example given for the `Author` field). This |
| 161 |
field can be used mutiple times if several persons reviewed the |
field can be used multiple times if several people reviewed the |
| 162 |
patch. |
patch. |
| 163 |
|
|
| 164 |
* `Last-Update` (optional) |
* `Last-Update` (optional) |
| 165 |
|
|
| 166 |
This field can be used to record the date when the meta-information |
This field can be used to record the date when the meta-information |
| 167 |
have been last updated. It should use the ISO date format |
was last updated. It should use the ISO date format `YYYY-MM-DD`. |
| 168 |
`YYYY-MM-DD`. |
|
| 169 |
|
Sample DEP-3 compliant headers |
| 170 |
|
------------------------------ |
| 171 |
|
|
| 172 |
|
A patch cherry-picked from upstream: |
| 173 |
|
|
| 174 |
|
Description: Fix regex problems with some multi-bytes characters |
| 175 |
|
Origin: upstream: http://sourceware.org/git/?p=glibc.git;a=commitdiff;h=bdb56bac |
| 176 |
|
Bug: http://sourceware.org/bugzilla/show_bug.cgi?id=9697 |
| 177 |
|
Bug-Debian: http://bugs.debian.org/510219 |
| 178 |
|
|
| 179 |
|
A patch created by the the Debian maintainer John Doe, which got forwarded |
| 180 |
|
and rejected: |
| 181 |
|
|
| 182 |
|
Description: Use FHS compliant paths by default |
| 183 |
|
Upstream is not interested in switching to those paths. |
| 184 |
|
. |
| 185 |
|
But we will continue using them in Debian nevertheless to comply with |
| 186 |
|
our policy. |
| 187 |
|
Forwarded: http://lists.example.com/oct-2006/1234.html |
| 188 |
|
Author: John Doe <john@foobar.com> |
| 189 |
|
Last-Update: 2006-12-21 |
| 190 |
|
|
| 191 |
|
A vendor specific patch not meant for upstream submitted on |
| 192 |
|
the BTS by a Debian developer: |
| 193 |
|
|
| 194 |
|
Description: Workaround for broken symbol resolving on mips/mipsel |
| 195 |
|
The correct fix will be done in etch and it will require toolchain |
| 196 |
|
fixes. |
| 197 |
|
Forwarded: not-needed |
| 198 |
|
Origin: vendor: http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=80;bug=265678 |
| 199 |
|
Bug-Debian: http://bugs.debian.org/265678 |
| 200 |
|
Author: Thiemo Seufer <ths@debian.org> |
| 201 |
|
|
| 202 |
Related links |
Related links |
| 203 |
------------- |
------------- |
| 211 |
* 2009-06-19: Replace Origin/Status/Patch with Origin/Forwarded. Add new |
* 2009-06-19: Replace Origin/Status/Patch with Origin/Forwarded. Add new |
| 212 |
fields Author and Last-Update. Rename Signed-off-by in Reviewed-by. |
fields Author and Last-Update. Rename Signed-off-by in Reviewed-by. |
| 213 |
Add a paragraph about the scope of the proposal. |
Add a paragraph about the scope of the proposal. |
| 214 |
|
* 2009-07-15: Make categorization in Origin optional. Make Origin optional |
| 215 |
|
if Author is present. |
| 216 |
|
* 2009-08-24: Add samples and mention difference with RFC-2822 related to |
| 217 |
|
the Description field. |
Parent Directory
| 
Revision Log
| 
Patch