Upgrade paths — renaming or splitting packages

WARNING: this page may be out of date. See current guidelines at https://docs.fedoraproject.org/en-US/packaging-guidelines/#renaming-or-replacing-existing-packages

For a very long time font package naming and splitting was under-specified. As a result the final adoption of strict splitting and naming guidelines requires the changing of many packages, while maintaining a working upgrade path.

Source package naming changes

Follow the usual procedure to remove the current package from rawhide, and post a review request for the new package.

For maximum efficiency this review request should:

• depend on the previous review ticket of your package,
• include the reference of the releng ticket blocking your previous package and,
• CC the fonts SIG bugs mailing list.

Renaming review are only required to check the sanity of the upgrade path, so they can be pretty quick. But do check your upgrade path first.

After the renaming review is done, please do not forget:

• to build your new font package for fedora-devel (rawhide),
• to create/update its wiki page,
• to update fedora-devel (rawhide) comps.

Binary package naming changes

(n:1) Many-to-one replacement

Replacing one or several old packages with a single new package is easy. You only need to obsolete your old package names in the new package:

%package -n %{fontname}-foo-fonts
[…]
Obsoletes: myold(sub)packagename1 < lastoldpackageversion-lastoldpackagerelease+1
Obsoletes: myold(sub)packagename2 < lastoldpackageversion-lastoldpackagerelease+1
[…]

%description -n %{fontname}-foo-fonts

…to the metadata of your new (sub)package.

Please do not forget to check the resulting upgrade path.

(n:m) Many to many replacement

When implementing our packaging guidelines requires the splitting of one package into several new (sub)packages things are a bit less easy. In that case you need to create a -compat subpackage corresponding to the (sub)package that was split, that obsoletes the old (sub)package and requires the new split (sub)packages. Please make it clear in its description that this is a utility package people should not depend on that will be eventually retired. Do not declare this compat package in comps.

%package compat
[…]
Obsoletes: myold(sub)packagename1 < lastoldpackageversion-lastoldpackagerelease+1
Obsoletes: myold(sub)packagename2 < lastoldpackageversion-lastoldpackagerelease+1
[…]
Requires:  mynew(sub)packagename1 = thisversion-thisrelease
Requires:  mynew(sub)packagename2 = thisversion-thisrelease
[…]

%description compat
This package only exists to help transition <mypackage> users to the new
package split. It will be removed after one distribution release cycle, please
do not reference it or depend on it in any way.

Please do not forget to check the resulting upgrade path.

Caveats

Can't I use my old package name instead of a -compat subpackage?

If you use your old package name you do not communicate to your users this is a temporary transitional metapackage to help upgrades. They'll keep referencing the old package name and even add more references to it, and you'll get stuck with it forever.

Plus, the existence of a metapackage which is not clearly identified is only going to confuse users.

Do I need to Provide my old package names?

Providing your old package names is not necessary to create working upgrade paths. Providing old package names is useful if you have other packages that depend on your old package name and you don't want them to change. In any way Fedora packaging best practices are to clean up old Provides and Obsoletes after two releases, so those other packages will have to change eventually.

Thus, you have the choice between:

• doing a clean break, and having other packagers adapt and complain now, or
• keep providing your old package names, till you eventually remove them, and people complain

Accumulating layers of compatibility rules in your spec file will only make it harder to understand and maintain by you and others.

You can identify the packages depending on your old package names with the following command, if you have the rawhide repository configured and activated in yum or dnf:

repoquery --repoid=rawhide --whatrequires myoldpackagename

Or:

dnf repoquery --repoid=fedora --whatrequires dnf

Whatever your decision it is polite to notify the maintainers of those other packages you've changed or going to change one of their dependencies. Please file the corresponding bugzilla tickets. If necessary use the bugzilla command in python-bugzilla to automate this task.

Testing and QA

To check an upgrade path works:

1. find a test Fedora system,
2. make sure none of the new packages are already installed,
3. install part or all of the old package set,
4. copy the new packages to a local directory,
5. run createrepo on this directory,
6. point dnf to it,
7. try a dnf upgrade.
8. if that fails, try to understand why, rpm -e whatever dnf upgrade installed and repeat from step 1.

You can also use:

rpm -qp --obsoletes mypackage

… to check the obsoletes declared by one of your new packages and,

dnf list obsoletes

before the dnf upgrate to check what dnf thinks about your new packages.

Notes:

Fonts in Fedora
The Fonts SIG takes loving care of Fedora fonts. Please join this special interest group if you are interested in creating, improving, packaging, or just suggesting a font. Any help will be appreciated.