Patches

There is no fixed rule for patch naming. The following are guidelines only.

Small patches (less than, say, a few KBytes) should be added to ${FILESDIR}. If you anticipate having several patches, it often helps to create version numbered subdirectories — ${FILESDIR}/${PV}/ is conventional. Patches are best named ${P}-what-it-does.patch (or .diff), where what-it-does is a two or three word description of what the patch is for. If the patch is to fix a specific bug, it is often useful to add in the bug number — for example, vim-7.0-cron-vars-79981.patch. If the patch is pulled from upstream's VCS repository, it can help to include the revision number in the patch name as a suffix to the version part — fluxbox-0.9.12-3860-menu-backups.patch.

Larger patches should be mirrored, preferably on the Gentoo Infrastructure. When mirroring patches, choosing a name that will not cause conflicts is important — the ${P} prefix is highly recommended here. Mirrored patches are often compressed with xz or bzip2. Remember to list these patches in SRC_URI.

Note: Patches included in ${FILESDIR} should never be compressed.

If a package requires many patches, even if they are individually small, it is often best to create a patch tarball to avoid cluttering up the tree too much.

Patch Descriptions

It is possible to include a description with a patch. This is often helpful when others come to work with your packages, or, indeed when you come back to take a look at your own package a few months later. Good things to include in comments are:

What the patch actually does. Bug numbers are good here.
Where the patch came from. Is it an upstream VCS pull, something from Bugzilla, something you wrote?
Whether the patch has been sent upstream, if applicable.

To include the description, simply insert it at the top of the patch file. The patch tool will ignore leading text until it finds something that looks like it might be a 'start patching' instruction, so as long as each description line starts with letters (rather than numbers, symbols or whitespace) there shouldn't be a problem. Alternatively, prefix each description line with a hash (that's #, or 'pound' to the USians) sign. It's also best to leave a single blank line after the description and before the main patch.

Here's a simple example (023_all_vim-6.3-apache-83565.patch) from the vim patch tarball:

# Detect Gentoo apache files properly. Gentoo bug 83565.

--- runtime/filetype.vim.orig   2005-03-25 01:44:12.000000000 +0000
+++ runtime/filetype.vim        2005-03-25 01:45:15.000000000 +0000
@@ -93,6 +93,9 @@
 " Gentoo apache config file locations (Gentoo bug #76713)
 au BufNewFile,BufRead /etc/apache2/conf/*/* setf apache

+" More Gentoo apache config file locations (Gentoo bug #83565)
+au BufNewFile,BufRead /etc/apache2/{modules,vhosts}.d/*.conf setf apache
+
 " XA65 MOS6510 cross assembler
 au BufNewFile,BufRead *.a65                    setf a65

Adding Patches to the tree

When adding a patch to the tree be sure to check that the patch doesn't have Git keywords in it that will be expanded (such as $Id$ ). If the patch contains these, it will break manifests unless you add it to the tree correctly. In the case that it does have the keywords, you should remove them. Afterwards they can be added like every other file:

git add files/${P}-the-cool-patch.patch