-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Pavel Nemec wrote:
We are working on patch naming for SUSE Package Conventions (http://forgeftp.novell.com//library/SUSE%20Package%20Conventions/spc.html)
Good initiative.
This is proposal and comments from community are welcome.
I sure hope so.
Reasons/ motivations: why we need this: ------------------------------------------------------- - backup maintainers - team working on bug fixing -> unified way of patching - tracking changes in patch, tracking mainstream patches
.. and IMO, the more conventions, the better. BTW, it would be nice if all SUSE packagers were applying their very own conventions ;)
1. Patch Name ----------------------- 1.1 Suffix ------------ We need to choose unified suffix for patch name. Commonly used suffixes are: "patch, diff, dif" ... Proposal: - use "patch" suffix, do not rename old patches. Do not use "dif" suffix any more.
Both .diff and .patch are equally good, so let's just pick one of them. I prefer .diff, but will use .patch from now on.
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.
And there are packages that have a different name than the source. For example, for KDE window decoration packages, I use the following convention (as there is none as of SUSE): e.g. flatknifty-1.2.3.tar.bz2 => kde3-windeco-flatknifty-1.2.3 I almost always use the name of the package, to do it like this: Source: http://..../moo-%{version}.tar.bz2 Source1: %{name}.desktop Source2: %{name}.logrotate Patch1: %{name}-fix-intptr.patch (i.e. use "%{name}-" as a prefix for all source and patch files, except the original source)
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.
Well, whatever, I prefer to stick to the package name. Don't think it's really critical, but it must be one of them (source name or package name). Obviously, when there are several original source tarballs, the "name" prefix of the patch should be the name of the source tarball it applies to.
1.2.2 Number ------------------ Number as version of source or package is heavily used in patch name.
I never do, I find it rather annoying and misleading. Before building a new version of a package, I check whether the patches still apply. If they do, fine, if they don't, I just port them but keep the [patch] filename.
This could confuse new maintainer because it suggest that patch is version dependent. If this package is not version dependent and package
Exactly.
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.
I won't stick to this one, that's just too complicated, too many if's. And using a version number in the patch filename has a drawback: when you have to port the patch because the sources don't match, you have to rename the patch file, e.g. from moo-1.2.3-fix-foobar.patch to moo-1.3.8-fix-foobar.patch The problem with that is SCM, as you can't clearly see that you've modified a patch in the change set. It's not as bad with SVN, as you can "svn move" a file to rename it, but it's still a bit tedious. And with CVS, you just don't see it at all and end up with files in Attic.
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
Sorry, I don't quite see the difference as of "words" between "lftp-compat-mode.patch" and "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
ACK.
- there are patch which fix problem which is caused by another part of system ( broken library, autobuild....). Patch name should reflect 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.
How is a fix "temporary" ? As long as it isn't fixed upstream, a patch is necessary, doesn't matter whether it's for the build system or for real sources.
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.
ACK.
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
I would say that is even more misleading ;) To know the history of the patches, just query the SCM. And if you don't care about the history but just want to look at a spec, IMO you should find them ordered from 1 to ..., especially when you have 51 patches ;)
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
Some RPM macros are applied regardless of whether they're commented out or now. Are you 100% sure that #%patch will not be applied ? I've seen pretty weird stuff with that. I'd suggest changing %patch2 to #patch2 instead of #%patch2 (unless, of course, you're sure no RPM 4.x version will apply #%patch2)
Comment should be also used, if patch is used differently than normal. e.g. (blender) Patch1: po.patch ^^^^^^^^^^^^^^^^^^^^^^^^ <nitpicking> Hey, that one doesn't comply to your proposal ;D Should be %{name}-po-fix-typos.patch </nitpicking>
Patch2: blender-home-to-datadir.patch # patch is applied only on x86-64 Patch5: Scons.patch [...] (same nitpicking as above ;))
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)
Why not just rewrite the spec and change the patch filenames so they match the conventions ?
- do not overwrite changelogs - preserve time stamps of file you do not modify.
ACK - -- -o) Pascal Bleser http://linux01.gwdg.de/~pbleser/ /\\ <pascal.bleser@skynet.be> <guru@unixtech.be> _\_v The more things change, the more they stay insane. -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.2 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFEbMw7r3NMWliFcXcRAoEKAJ9+OsE0SM7kiBu6GWg/eoJ82Qe+sgCeL0Pr sS5nuqbTnoFeg4Td0yWfB7E= =TYE9 -----END PGP SIGNATURE-----