We are working on patch naming for SUSE Package Conventions
(http://forgeftp.novell.com//library/SUSE%20Package%20Conventions/spc.html)
This is proposal and comments from community are welcome.
Reasons/ motivations: why we need this:
-------------------------------------------------------
- backup maintainers
- team working on bug fixing -> unified way of patching
- tracking changes in patch, tracking mainstream patches
1. Patch Name
-----------------------
1.1 Suffix
------------
We need to choose unified suffix for patch name. Commonly used suffixes
are: "patch, diff, dif"
Suffix "Patch" and "Diff" are most commonly used. There is no rational
reason why one "Patch" or "Diff" should NOT be used. "Diff" suffix is
associated with shared mime info
Proposal:
- use "patch" suffix, do not rename old patches. Do not use
"dif" suffix any more.
1.2 Naming
---------------
Name of package should be very intuitive and should tell maintainer what
this patch actually fix. Name of patch should consist of: Name, Number,
Mnemonic hint
1.2.1 Name
---------------
There is two way for choose patch name, use package name, or use source
name. There are packages with more than one source in package.
Proposal:
- use name of source which patch is apply to. Patch should not
fix files from different source.
- if is not possible use name of source, use name of package
instead.
1.2.2 Number
------------------
Number as version of source or package is heavily used in patch name.
This could confuse new maintainer because it suggest that patch is
version dependent. If this package is not version dependent and package
is updated to new version, all patch had to be updated. In SUSE, there
are many packages which contains patch, which are not sent to upstream,
because they fix SUSE specific problems.
Proposal:
- use no number at all for patch which are not meant to be send
in upstream (SUSE specific, temporary distribution dependent fix ....)
- use number for patch which are only for this version of
package (source), this patch should be sent to upstream. This number
should be changed when updating to new version if we still expect this
patch to be accepted by upstream. If no, number should be removed from
this patch.
1.2.3 Mnemonic hint
---------------------------
Mnemonic hint should tell (together with changelog) what this patch fix.
There are only common hints how to do useful hints.
Proposal:
- use '-' for separate section in name and '_' for separating words
e.g.: 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). We could consider creating table of commonly used hints.
e.g.: 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....). Patch name should
reflex this. 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.
2. 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.
Proposal:
- mention add or remove patch in changelog
e.g. [ ...]
- added patch -gcc-error.patch
- use number of bug from bugzilla., Name of bugzilla should be
used if it is not obvious
e.g. fixed gcc error [#32423]
fixed gcc error, openoffice [#3224324]
- use reference to security ID in changelog
e.g. - fixed completely broken SplTempFileObject [php#37257]
- if fix is more complicated, additional info in header of patch
file should be present!
- 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...)
3. Patch in specfile
-------------------------
Main problem with patch in specfile is numbering. When patches are added
they have increasing number. Php example:
Patch1: php5-config.patch
Patch2: php5-phpize.patch
Patch3: php5-apache_sapi_install.patch
Patch4: php5-php-config.patch
Patch5: php-%{version}-include_path.patch
[ ... snip, there are about 51 patches]
When patch is removed, there are hole in specfile, which could look
ugly. But renumbering is time consuming. There is possible to use unused
number, but adding position in spec file should be preserved. Example
Patch1: php5-config.patch
Patch3: php5-apache_sapi_install.patch
Patch4: php5-php-config.patch
Patch5: php-%{version}-include_path.patch
Patch2: php5-new.patch
When patch is commented in spec file and not deleted, there should be
comment, explaining this.
e.g.
# FIXME: This patch should be backported.
#%patch2
# Uncomment this patch, if automake fails.
#%patch3
Comment should be also used, if patch is used differently than normal.
e.g. (blender)
Patch1: po.patch
Patch2: blender-home-to-datadir.patch
# patch is applied only on x86-64
Patch5: Scons.patch
[...]
4. Common advise
-------------------------
- when fixing package, try to keep style convention set by author of
this package (if it is still any)
e.g. some one write bugzilla number as "#234345", [#33453453],
(#2342342)
- do not overwrite changelogs
- preserve time stamps of file you do not modify.
--
Pavel Nemec
package-maintainer
http://en.opensuse.org/Czech_Packagers_Team
---------------------------------------------------------------------
SuSE CR, s.r.o. e-mail: [EMAIL PROTECTED]
Drahobejlova 27 tel:+420 2 9654 2373
190 00 Praha 9 fax:+420 2 9654 2374
Ceska republika http://www.suse.cz
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
