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: pnemec@suse.cz Drahobejlova 27 tel:+420 2 9654 2373 190 00 Praha 9 fax:+420 2 9654 2374 Ceska republika http://www.suse.cz
-----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/
/\\
Hi,
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.
A "tempfix" might be a fix that works around a bug in another package and will be dropped as soon as the other package is fixed, but cannot be sent upstream because it's not upstream's problem. For example, a workaround for a miscompilation.
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.
Only macros that expand to multiple lines are affected by this problem. %patch expands to a single line, so just adding a # sign at the beginning of the line is safe for %patch.
I'd suggest changing %patch2 to #patch2 instead of #%patch2 (unless, of course, you're sure no RPM 4.x version will apply #%patch2)
The correct thing in such a case is to duplicate the % sign. For example, %suse_update_desktop_file is a macro that expands to multiple lines. This means that #%suse_update_desktop_file does not work. But %%suse_update_desktop_file works. Nothing we need to worry about when using %patch. Andreas Hanke -- Bis zu 70% Ihrer Onlinekosten sparen: GMX SmartSurfer! Kostenlos downloaden: http://www.gmx.net/de/go/smartsurfer
Hi, On Thu, 18 May 2006 at 21:34, Pascal Bleser wrote:
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 ?
rewriting the spec file is OK when taking over maintainership for a package, but when you fix a package that is normally maintained by someone else, it's better to be as little intrusive as possible, or ask the regular maintainer if it is OK with him that you turn his package upside down. cu Reinhard
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Reinhard Max wrote:
Hi,
On Thu, 18 May 2006 at 21:34, Pascal Bleser wrote:
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 ?
rewriting the spec file is OK when taking over maintainership for a package, but when you fix a package that is normally maintained by someone else, it's better to be as little intrusive as possible, or ask the regular maintainer if it is OK with him that you turn his package upside down.
Of course, didn't mean to say the opposite ;)
But complying with the guidelines isn't a triviality either :)
cheers
- --
-o) Pascal Bleser http://linux01.gwdg.de/~pbleser/
/\\
On Thu, May 18, 2006 at 09:34:19PM +0200, Pascal Bleser wrote:
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)
%patch is not a macro (it just looks like one). Same is true for %prep, %package, %changelog and the like. Using '#' on such pseudo macros works. Cheers, Michael. -- Michael Schroeder mls@suse.de main(_){while(_=~getchar())putchar(~_-1/(~(_|32)/13*2-11)*13);}
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. I see, but i still think that name of source is better. It is not critical with one source package, though.
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. That is exactly point for numbering patches. When patch is numbered, you should investigate if patch is not allready in upstream. All "reasonable" patches should go to upstream.
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. Patch numbering have some drawbacks, everything have. But i still think that is better to do some work when updating, that do a lot of work searching every patch what to do. The if`s are really sample actually. If this fix is "SUSE only" (menu, file position, icons ...) no number. If patch have number, it should be send to upstream..
- 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. There are cases when package is broken because of error in other package(s). This is really special case. Such a fix is neither meant to be sent to upstream, nor stay with package for long time.
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> You are right. This is "old" patch. Before proposal ;-)
Patch2: blender-home-to-datadir.patch # patch is applied only on x86-64 Patch5: Scons.patch [...]
(same nitpicking as above ;)) Same as above.
participants (5)
-
andreas.hanke＠gmx-topmail.de -
Michael Schroeder -
Pascal Bleser -
Pavel Nemec -
Reinhard Max