[[meta title="DEP-3: Patch Tagging Guidelines"]] Title: Patch Tagging Guidelines DEP: 3 State: DRAFT Date: 2009-06-12 Drivers: Raphael Hertzog 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 the [Patch Tracking System](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 "`# `". For 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. The set of fields ends on the first empty line. Free-form comments can follow and be used for any other information that does not fit in the structured content. Standard fields --------------- In the following section, `` 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 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 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-` or `Bug` (optional) 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. * `Forwarded` (optional) 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. 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). * `Author` (optional) This field can be used to record the name and email of the patch author (ex: "`John Bear `"). 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. * `Reviewed-by` (optional) This field can be used to document the fact that the patch has been 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) 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 ------------- * [Ubuntu's patch tagging guidelines](https://wiki.ubuntu.com/UbuntuDevelopment/PatchTaggingGuidelines) Changes ------- * 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.