r63 - /web/deps/dep3.mdwn
hertzog at users.alioth.debian.org
hertzog at users.alioth.debian.org
Sat Jun 13 19:33:54 UTC 2009
Author: hertzog
Date: Sat Jun 13 19:33:53 2009
New Revision: 63
URL: http://svn.debian.org/wsvn/dep/?sc=1&rev=63
Log:
More improvements to the presentation
Modified:
web/deps/dep3.mdwn
Modified: web/deps/dep3.mdwn
URL: http://svn.debian.org/wsvn/dep/web/deps/dep3.mdwn?rev=63&op=diff
==============================================================================
--- web/deps/dep3.mdwn (original)
+++ web/deps/dep3.mdwn Sat Jun 13 19:33:53 2009
@@ -30,8 +30,8 @@
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 http://patch-tracking.debian.net can display
-them.
+available so that tools like the [Patch Tracking
+System](http://patch-tracking.debian.net) can display them.
Structure
@@ -43,8 +43,10 @@
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 "`# `" so that
-they start with a space once "`# `" has been stripped from the beginning.
+multi-line fields, the subsequent lines should start with
+"`#` " (dash followed by two spaces) so that
+they start with a space once "`#` " (dash followed by a space) has been
+stripped from the beginning.
Standard fields
@@ -54,10 +56,13 @@
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
@@ -66,19 +71,27 @@
patch. It should typically be the name and email of the patch author
(ex: "`John Bear <foo at 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 "<vendor>-specific" (the patch must not be
@@ -90,11 +103,13 @@
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.
+
+ 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
@@ -105,11 +120,12 @@
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",
+
+ 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
+ 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
@@ -119,7 +135,7 @@
Related links
-------------
- * https://wiki.ubuntu.com/UbuntuDevelopment/PatchTaggingGuidelines
+ * [Ubuntu's patch tagging guidelines](https://wiki.ubuntu.com/UbuntuDevelopment/PatchTaggingGuidelines)
Changes
-------
More information about the dep-commits
mailing list