openSUSE:Patches Guidelines for X11:XOrg Project
Build Service Tutorial · Tips & Tricks · Cross Distribution Howto · Packaging checks
Desktop menu categories · RPM Macros · Scriptlets · Init scripts · How to write good changes
To achieve this the goal is to keep the number of patches in a source package at a minimum. Any patches that remain need to follow certain guidelines so one can easily obtain an overview over the purpose and intended lifetime of patches.
Patch content format:
Patch should contain a header giving information about the patch -- the preferred format is what is created by 'git format-patch' or 'git show'. Diffstats would be nice but are not really required.
The header should contain:
- The author:
- Add a line: 'Author: My Name <Name@my.domain>'
- A subject (usually the summary line from git commit.)
- Add a line: 'Subject: ...'
- If the patch has been upstreamed.
- Add a line: 'Patch-Mainline: ["Upstream"/release number|"To be upstreamed"|"N/A"|"Never"|"Temporary"]'.
- If available the number of the release which first contained a this patch should be provided. Most states are self explanatory. The state "Temporary" requires further explanation: This state should be used for fixes which are necessary to work around issues that will be or have been solved differently upstream (due to changes in code) or which are required to fix release specific build issues. Patches for the latter purpose should be wrapped by if-clauses in the spec file to include them only for the releases required. Temporary patches must *not* survive the next source tarball update cycle unless they are required to work around release specific build issues. The description *must* explain why this workaround is required. If state is 'Never' the comment must explain why.
- The git commit ID of the upstream project (if it is a git-hosted project)
- Add a line: 'Git-commit: <commit-ID>'
- Any references such as bug ID (like bnc #N, any url relevant, CVE nr. for security fixes please also see openSUSE:Packaging_Patches_guidelines for abbreviations)
- Add a line: 'References: <reference> ...'
- Who is responsible for this patch (if not the same as the author)
- Add a line: 'Signed-off-by: My Name <firstname.lastname@example.org>'
Patches should apply with -p0 or -p1.
File name format:
The file name should have the form:
- 'N' for: N/A
- 'n' for: never to be upstreamed.
- 'u' for: to be upstreamed
- 'U' for: already be upstreamed, ie from upstream
- 'T' for: temporary
<package-or-driver> should identify the subpackage in an rpm source package if more than one exists. To make the patch name a bit shorter it does suffice to name the part of the package name which uniquely identifies the package (ie. intel for xf86-video-intel). <patchname> can be anything the author chooses. It should be slightly descriptive (for instance the subject line with all spaces replaced by underscores - as done by git format-patch).
OSC changelog entries
OSC changelog entries should provide
- the names of the patches changed,
- a reference if applicable (if it is a new patch a bugzilla entry with more detailed information is required),
- an (abbreviated) summary and who was responsible for the patch in OSC (not upstream) - if this is not the same as the committer.