Upgrade paths — renaming or splitting packages

From FedoraProject

Revision as of 07:15, 27 May 2009 by Sundaram (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

A page of the Fonts Special Interest Group

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 rel-eng 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.


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[1]. 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[2]

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:

repoquery --repoid=rawhide --whatrequires myoldpackagename

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],
  3. install part or all of the old package set,
  4. copy the new packages to a local directory[4],
  5. run createrepo on this directory[5],
  6. point yum to it[6],
  7. try a yum update.
  8. if that fails, try to understand why, rpm -e whatever yum update 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,

yum list obsoletes

before the yum update to check what yum thinks about your new packages[7].


  1. Yes, we know rpmlint will ask for Provides. Use your common sense and do not follow rpmlint warnings blindly.
  2. By this time they'll have forgotten about the operation and get used to your compatibility provides.
  3. It would confuse the tools.
  4. If you're creating them:
    1. adapt the previous spec file or create a new one,
    2. mock/koji-build the result.
  5. createrepo <directory>
  6. Use a repo file such as this one:
  7. But that won't check scriptlets and other packaging bits so do check yum update works afterwards.

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.