r65 - /web/deps/dep3.mdwn
hertzog at users.alioth.debian.org
hertzog at users.alioth.debian.org
Fri Jun 19 09:16:03 UTC 2009
Author: hertzog
Date: Fri Jun 19 09:16:01 2009
New Revision: 65
URL: http://svn.debian.org/wsvn/dep/?sc=1&rev=65
Log:
First set of changes following public discussion
Replace Origin/Status/Patch with Origin/Forwarded. Add new
fields Author and Last-Update. Rename Signed-off-by in Reviewed-by.
Modified:
web/deps/dep3.mdwn
Modified: web/deps/dep3.mdwn
URL: http://svn.debian.org/wsvn/dep/web/deps/dep3.mdwn?rev=65&op=diff
==============================================================================
--- web/deps/dep3.mdwn (original)
+++ web/deps/dep3.mdwn Fri Jun 19 09:16:01 2009
@@ -62,77 +62,74 @@
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.
+ explanation of the patch and its history.
+
+ This field should explain why the patch is vendor-specicific (ex:
+ branding patch) when that is the case. If the patch has been submitted
+ upstream but has been rejected, the description should also document
+ why it's kept and what were the reasons for the reject.
* `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.
+ This field should document the origin of the patch. It starts with a
+ single keyword that 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), "vendor" for a patch created
+ by Debian or another distribution vendor, or "other" for all other
+ kind of patches. It can be optionally followed by a colon with
+ leading/trailing spaces before/after it. In that case, all the content
+ after the colon contains supplementary information defining in more
+ details the origin of the patch. In most cases, it should be a simple
+ URL. For patches backported/taken from upstream, it should point into
+ the upstream VCS web interface when possible, otherwise it can simply
+ list the relevant commit identifier (it should be prefixed with
+ "commit:" in that case). For other cases, one should simply indicate
+ the URL where the patch got grabbed (mailing list archives,
+ distribution bugtrackers, etc.) when possible.
* `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.
+ It contains one URL pointing to the related bug (possibly fixed by the
+ patch). The `Bug` field is reserved for the bug URL in the upstream
+ bug tracker. Those fields can be used multiple times if several
+ bugs are concerned.
- * `Patch` (optional)
+ * `Forwarded` (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.
+ Any value other than "no" or "not-needed" means that the patch
+ has been forwarded upstream. Ideally the value is an URL proving
+ that it has been forwarded and where one can find more information
+ about its inclusion status.
- * `Commit` (optional)
+ If the field is missing, its implicit value is "yes" if the "Bug"
+ field is present, otherwise it's "no". The field is really required
+ only if the patch is vendor specific, in that case its value should
+ be "not-needed" to indicate that the patch must not be forwarded
+ upstream (whereas "no" simply means that it has not yet been done).
- 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.
+ * `Author` (optional)
- * `Status` (optional)
+ This field can be used to record the name and email of the patch author
+ (ex: "`John Bear <foo at bar.net>`"). Its usage is recommended when the
+ patch author did not add copyright notices for his work in the patch
+ itself. It's also a good idea to add this contact information when
+ the patch needs to be maintained over time because it has very little
+ chance of being integrated upstream.
- 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.
-
- * `Signed-off-by` (optional)
+ * `Reviewed-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.
+ reviewed by someone. It should list her name and email in the standard
+ format (similar to the example given for the `Author` field). This
+ field can be used mutiple times if several persons reviewed the
+ patch.
+ * `Last-Update` (optional)
-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.
+ This field can be used to record the date when the meta-information
+ have been last updated. It should use the ISO date format
+ `YYYY-MM-DD`.
Related links
@@ -144,4 +141,5 @@
-------
* 2009-06-12: Initial draft by Raphaël Hertzog.
-
+* 2009-06-19: Replace Origin/Status/Patch with Origin/Forwarded. Add new
+ fields Author and Last-Update. Rename Signed-off-by in Reviewed-by.
More information about the dep-commits
mailing list