r60 - in /web: deps/dep3.mdwn index.mdwn
hertzog at users.alioth.debian.org
hertzog at users.alioth.debian.org
Fri Jun 12 21:11:17 UTC 2009
Author: hertzog
Date: Fri Jun 12 21:11:16 2009
New Revision: 60
URL: http://svn.debian.org/wsvn/dep/?sc=1&rev=60
Log:
Initial version of DEP3
Added:
web/deps/dep3.mdwn
Modified:
web/index.mdwn
Added: web/deps/dep3.mdwn
URL: http://svn.debian.org/wsvn/dep/web/deps/dep3.mdwn?rev=60&op=file
==============================================================================
--- web/deps/dep3.mdwn (added)
+++ web/deps/dep3.mdwn Fri Jun 12 21:11:16 2009
@@ -1,0 +1,117 @@
+[[meta title="DEP-3: Patch Tagging Guidelines"]]
+
+ Title: Introducing Debian Enhancement Proposals (DEPs)
+ DEP: 3
+ State: DRAFT
+ Date: 2009-06-12
+ Drivers: Raphael Hertzog <hertzog at 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 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 "# " so that
+they start with a space once "# " has been stripped from the beginning.
+
+
+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 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
+ 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.
+
+
+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.
+
+Changes
+-------
+
+* 2009-06-12: Initial draft by Raphaël Hertzog.
+
Modified: web/index.mdwn
URL: http://svn.debian.org/wsvn/dep/web/index.mdwn?rev=60&op=diff
==============================================================================
--- web/index.mdwn (original)
+++ web/index.mdwn Fri Jun 12 21:11:16 2009
@@ -8,7 +8,7 @@
[DEPÂ 0](deps/dep0)|__Accepted__|Introducing Debian Enhancement Proposals|[VCS](svn://svn.debian.org/svn/dep/web/deps/dep0.mdwn) [Web](http://svn.debian.org/wsvn/dep/web/deps/dep0.mdwn?op=log&rev=0&sc=0&isdir=0)
[DEPÂ 1](http://wiki.debian.org/NmuDep)|__Accepted__|Clarifying policies and workflows for Non Maintainer Uploads (NMUs)|[Wiki](http://wiki.debian.org/NmuDep)
[DEPÂ 2](deps/dep2)|_No draft yet_|Classification and self-assessment of maintenance level|<!-- [VCS](svn://svn.debian.org/svn/dep/web/deps/dep2.mdwn) [Web](http://svn.debian.org/wsvn/dep/web/deps/dep2.mdwn?op=log&rev=0&sc=0&isdir=0) -->
-[DEPÂ 3](deps/dep3)|_No draft yet_|Patch Tagging Guidelines|<!-- [VCS](svn://svn.debian.org/svn/dep/web/deps/dep3.mdwn) [Web](http://svn.debian.org/wsvn/dep/web/deps/dep3.mdwn?op=log&rev=0&sc=0&isdir=0) -->
+[DEPÂ 3](deps/dep3)|__Draft__|Patch Tagging Guidelines|[VCS](svn://svn.debian.org/svn/dep/web/deps/dep3.mdwn) [Web](http://svn.debian.org/wsvn/dep/web/deps/dep3.mdwn?op=log&rev=0&sc=0&isdir=0)
[DEP 4](deps/dep4)|__Draft__|Translation packages in Debian (TDebs)|[VCS](svn://svn.debian.org/svn/dep/web/deps/dep4.mdwn)
[DEP 5](deps/dep5)|__Draft__|Machine-parseable debian/copyright|[VCS](svn://svn.debian.org/svn/dep/web/deps/dep5.mdwn)
"""]]
More information about the dep-commits
mailing list