Hello, please find below a first draft of DEP-3 that I called Patch Tagging Guidelines. The idea is to standardize a set of meta-information to embed in patches that we apply. Please review, share your comments and ideas of enhancements.
If (and once) we have consensus that it is good idea to standardize those information, we can take supplementary steps to ensure they are not forgotten and correctly filled: - lintian can advise using this format in quilt-patch-missing-description or dpatch-missing-description, it can also check for correctness when packages are trying to use of this format - in format "3.0 (quilt)" dpkg-source would create initial headers respecting this format automatically based on the changelog when it creates a new patch - fix some tools to correctly preserve those information (apparently cdbs-edit-patch is not wise enough to do this by default) - the developers-reference could be updated to recommend usage of this format The latest version of the DEP is on the web: http://dep.debian.net/deps/dep3/ Text version follows: Title: Patch Tagging Guidelines DEP: 3 State: DRAFT Date: 2009-06-12 Drivers: Raphael Hertzog <[email protected]> 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 "`# <field>`". 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, `<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 <[email protected]>`") 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. * `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. 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. Related links ------------- * [Ubuntu's patch tagging guidelines](https://wiki.ubuntu.com/UbuntuDevelopment/PatchTaggingGuidelines) Changes ------- * 2009-06-12: Initial draft by Raphaël Hertzog. Cheers, -- Raphaël Hertzog Contribuez à Debian et gagnez un cahier de l'admin Debian Lenny : http://www.ouaza.com/wp/2009/03/02/contribuer-a-debian-gagner-un-livre/ -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected]
