Patch Name Convention

Please do not edit text at the moment. Discusion about this text take place at [1] and [2]

One of the common thing when dealing with new package (creating, taking over, updating) is creating patch. This document should provide collection of recommendation which will help packagers to achieve consistent format of packages (specfile).

When creating patch you have do some basic steps:

• create patch: this is not covered by this document
• choose name for patch: Chapter 1
• provide some information about what you did with package: Chapter 2 and 3

Some additional usefull information are in Chapter 4.

1. Patch Name

---

Name of patch is usually compound from:

${NAME}-${NUMBER}-${TEXT}.${SUFFIX}

Example:

• amanda-2.5.0-mtx.diff
• blender-2.41-missing_header.patch

Name of patch should be very intuitive and should tell maintainer what this patch fix.

In case that patch are taken from elsewhere (upstream, others distribution ... ) you should consider preserve original naming scheme.

Suffix

You can meet 3 kind of suffix: dif, diff, patch. dif should not be used anymore.

diff and patch are both heavily used. There is no rational reason why patch or diff should NOT be used. diff is format name of program of same name, and itis associated with shared mime info. We recommend use patch suffix, do not rename old patches. Do not use dif. suffix any more.

Name

There is two way for choose patch name, use package name, or use source name. There are packages with more than one source file in package and patch name should take this in care. We recommend use name of source which patch is apply to. Patch should not fix files from different source. If it is not possible (or is very cumbersome) to use name of source, use name of package instead.

Example package enlightenment contains 4 sources and 7 patches. Patch use name of source as name:
enlightenment-config.patch
enlightenment.desktop
enlightenment-eesh.patch
enlightenment-gcc_error.patch
enlightenment-kde2.patch
enlightenment-koreanpack.tar.gz
enlightenment-makefile.patch
enlightenment-menu.patch
enlightenment.spec
enlightenment-SuSEmenu.patch
enlightenment-0.16.7.2.tar.bz2
themes.tar.bz2

Number

Number as version of source or package is heavily used in patch name. Sometimes numbers are used to indicate version of program from patch is. Sometimes numbers indicate actual version of package, and sometimes numbers are not used at all.

This could confuse new maintainer. All patch which solve some problem should be send to upstream. Though packages which contains patch, which are not sent to upstream, because they fix SUSE specific problems, they fix old version of program (backported patch) or upstream do not want accept our patch.

We recommend:

• use number of program which your patch fix, send your patch to upstream
• if patch is not taken, patch is backported, or patch fix your specific need, do not use number
• when updating package and upstream did not take your patch yet, you should rename your patch.

Text - Mnemonic hint

Text should consist of some word which hint you what patch do. There are only common hints how to do useful hints.

• use '-' for separate section in name and '_' for separating words

Example:

gcc-really_useful.patch

enlightenment-gcc_error.patch

lftp-compat_mode.patch

graphviz-fix_swig_template.patch

• if fixed problem could not be easily hinted by short name, you can use bugzilla number, or security bug reference ID (like CVE, PMASA, see "Using Bugzilla in changelog" for more details).

Example:

CVE-2005-3353.patch

PMASA-2005-6.patch

php-5.1.2-phpbug-36208.patch

• there are patch which fix problem which is caused by another part of system ( broken library, autobuild....) or different package. Patch name could hint such case. We propose to use buildfix/temporaryfix/runfix for such patch. This patch should be removed as soon as possible (probably when updating to new version)
• buildfix - if this package could be builded, this patch could be safely removed.
• runfix - if this package could be runed without this patch, this patch could be safely removed.
• temporaryfix - all other temporary fix.

Changelog

---

All changes in package (adding/removing patch, changing spec file ...) should be mentioned in changelog. From name of patch changelog and comments in patch should be clear what change was made. Comments about patch in changelog should be short and clear. Recomendation:

• mention added or removed patch in changelog
• use number of bug from bugzilla. Name of bugzilla should be used if it is not obvious. See bugtable.
• if fix is more complicated,add info into header of patch not into changelog
• additional info in patch should be present also in patch which will be presented in package for long time (program is not developed any longer...)

Example from php5 package:

-------------------------------------------------------------------

Wed May 3 15:16:05 CEST 2006 - postadal@suse.cz

- fixed completely broken SplTempFileObject [php#37257]

(phpbug-37257.patch)

- fixed problem with with $_POST array [php#37276]

(phpbug-37276.patch)

------------------------------------------------------------------

Bug Table

Table of most used bugzilla symbol.

Abbrevation	Bugzilla	Note
[#1234]	Novell bugzilla	bug number 1234, see [3] for more details
[php#37394]	Php bugzilla	bug number 37394, see ??
[oo#1334]	OpenOffice bugzilla	issue number 1334, see [4] for more details
CVE	???	??
PMASA	???	??

Patch in specfile

---

You can add comments to patch when you define patch:

Examples from enlightenment:

#

# patches for korean pack

Patch10:  %{name}-kde2.patch

Patch11:  %{name}-SuSEmenu.patch

Patch12:  %{name}-menu.patch

or when applying patch:

Examples from enlightenment:

...

 %patch3

# patch10,11,12 are applied in the install phase

%build

...

When patch is commented in spec file and not deleted, there should be comment, explaining why patch is commented and not deleted directly.

Examples:
::#...

# FIXME: This patch should be backported.

#%patch2

#

# Uncomment this patch, if automake fails.

#%patch3

Common advise

---

• when fixing package, try to keep style convention set by author of

this package (if it is still any).

• do not overwrite changelogs
• preserve time stamps of file you do not modify. Use cp -p or set your default file manager to preserve attributes when copying [5]