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.

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:

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