DICE RPM Naming Guidelines

ALERT! Note that items marked QUESTION? are particularly up for debate. Comments appreciated on these items in particular.

Introduction

The package naming guidelines for DICE and its comonent parts, LCFG Core; Edinburgh Environment and DICE itself, are designed to do a number of things:

  • Play nicely with the package naming for upstream rpm repositories:
    • Fedora Core
    • Fedora Extras
    • JPackage
  • Prevent potential problems with compatability with third party rpm sources such as RPMforge.
  • Allow automatic sorting of DICE, LCFG and Edinburgh Environment RPMs into their respective RPM repositories.
  • Not be so complex that people have no idea how to name packages.

The starting point for the design of these package naming guidelines is the Fedora Package Naming Guidelines. It is highly recommended that anyone building packages for DICE read these guidelines first as the DICE RPM Naming Guidelines are based on them.

Executive Summary

In Summary, the full DICE Package Naming Policy is basically:

                       /----------------- %{release} ----------------\
   %{name}-%{version}-%{upstream_release}.%{repo_name}.%{local_release}-%{arch}.rpm

Where:

%{upstream_release}
Is the upstream package %{release} if it exists otherwise 0 (zero).
%{repo_name}
One of the DICE layer names - currently: lcfg, ed and dice.
%{local_release}
If %{upstream_release} is 0 then %{local_release} adheres to the same rules as for the %{release} tag in the Fedora Package Naming Guidelines. Otherwise it is a single integer indicating the local revision of the package.

... and the rules for Changing the %{release} Tag of RPMs from Third Party Repositories also apply. See the Example Package Names section for some quick examples.

The Basics - %{name}, %{version} and %{arch}

The normal composition of package names in Fedora Core and Fedora Extras is usually along the lines of:

   %{name}-%{version}-%{release}-%{arch}.rpm

DICE, LCFG and Edinburgh Environment RPMs use exactly the same %{name}, %{version} and %{arch} naming rules as the Fedora Package Naming Guidelines. There are however some local specialisations:

  • LCFG Component packages (including ones for DICE) should have a %{name} of the form: lcfg-%{component_name}.
  • QUESTION? DICE only software that will never be used outside DICE should have a %{name} of the form: dice-%{package_name}, unless it is an LCFG component.

The Fiddly Bit - %{release}

With the advent of the Fedora Project and the proliferation of third party RPM repositories for Fedora Core the %{release} tag has become subject to quite a lot of abuse. This is mainly because neither the package management applications or RPM itself currently have sufficient support for dealing with the package upgrade path and package priority issues that third party repositories introduce. To fix these issues properly the package management applications need to become more intelligent and RPM needs better metadata tags (or better use of them at least). Until this happens overloading the %{release} tag to include some of this metadata and force the package management applications to do the "right" thing is seemingly the best option.

Package Upgrade Path

-- CarwynEdwards - Remove this?

Ensuring a sensible package upgrade path means that when a new RPM enters the set of RPMs to be considered for installation the right thing will happen with respect to the version and release numbers associated with the RPM and its predecessors. This not only has to hold for additions to a given base platform (e.g. Fedora Core with Fedora Extras), but also between upgrades to the base platform (e.g. the transition from Fedora Core 3 to Fedora Core 4).

For a RPM Repository such as the DICE repository set (lcfg, ed and dice) this basically means that when an RPM is added upstream it should take priority over any local RPMs as long as it is actually newer. This is to allow users to benefit from the upstream improvements as soon as possible (e.g. security or bug fixes). However, any packaging guidelines must also allow for local modifications to upstream RPMs and multiple revisions of such localised tweaks. The most established approach to meeting these requirements is the The Upstream Release and Local Suffix Approach to modifying the %{release} tag explained later in these guidelines.

Third Party Repositories

-- CarwynEdwards - Remove this?

The The Upstream Release and Local Suffix Approach to %{release} tagging only ensures sensible upgrade paths relative to the base platform of Fedora Core and Fedora Extras. It does not hold when considered relative to other third party RPM repositories unless special arrangements exist between the third party repositories to ensure consistency (i.e. they all use the same rules). An example of such an arrangement is the RPMforge collection of repositories. The member repositories of RPMforge have policies in place that ensure that RPMs are consistent across all member respoitories. This means that all the RPMforge repositories can be used together on top of Fedora Core and Fedora Extras.

The need for such inter-repository arrangements stems from the possibility of duplicate or conflicting RPMs, especially in terms of %{release} tags, appearing in one or more third party repositories. The one, but significant, problem with such arrangements is that they only work if you are part of agreement or can work within its bounds. Unfortunaltey the requirements for DICE do not allow this since we need to be able to more than the bounds allow.

What does this mean? It means that all other non-upstream RPM repository %{release} tagging policies have to be assumed to be incompatible with the DICE Package Naming Guidelines. This does not mean that the packages are incompatible, on the contrary if they are using the same base platform (Fedora Core plus Fedora Extras) they are highly likely to be, but it does mean that the packages will need to have their %{release} tags changed. The rules for changing the %{release} tag are specified in the Changing the %{release} Tag of RPMs from Third Party Repositories section.

Changing the %{release} Tag of RPMs from Third Party Repositories

The rules for changing the %{release} tags in RPMs from third party RPM repositories are:

  • If the RPM with the same %{name}-%{version} does not exist in an upstream repository then the %{release} tag on the third party RPM should be removed and completely replaced. The new tag should follow the The Upstream Release and Local Suffix Approach considering the package to be a non-upstream package.
  • If an RPM with the same %{name}-%{version} exists in an upstream repository then the differences should be merged into the upstream package. This makes the resultant package a local modification of an upstream package and hence the %{release} should follow the appropriate rules from the The Upstream Release and Local Suffix Approach to naming.

The Upstream Release and Local Suffix Approach

This is a very simple method of both tagging local packages and allowing for sensible upgrade paths. The two parts and the rules associated with them are described below. The high level view of the full RPM name using the Upstream Release and Local Suffix is:

                       /----------------- %{release} ----------------\
   %{name}-%{version}-%{upstream_release}.%{repo_name}.%{local_release}-%{arch}.rpm
                       \-- Upstream ---/   \------ Local Suffix -----/
                        \- Release ---/

These parts are referenced in the descriptions below.

The Upstream Release

The Upstream Release part refers to the %{upstream_release} part of the %{release}. This should follow the following rules:

  • If the package %{name}-%{version} exists in an upstream repository (exact match) then %{upstream_release} should be the value of the %{release} tag from the upstream package. This will usually be the case when a local modification is made to an upstream package.
  • If the package %{name}-%{verison} does not exist in an upstream repository then %{upstream_release} should be set to 0 (zero). This will ensure that any subsequent addition of the package %{name}-%{version} to an upstream repository will override the local one.

The Local Suffix

The Local Suffix refers to the %{repo_name}.%{local_release} part of the %{release}. This should follow the following rules:

%{repo_name}
This should be one of the DICE layer names. These are currently lcfg, ed and dice. Note that these local %{repo_name} names must be limited to strings that are not likely to appear in the alphanumeric parts of the %{upstream_release} and %{local_release} tags (e.g. alpha, beta, pre, rc).
%{local_release}
This is the local package revision number that adheres to the same rules as the Fedora Package Naming Guidelines %{release} field if %{upstream_release} is 0 otherwise it is a single integer indicating the local revision of the package.

Example Package Names

Here are some example package namings corresponding to the various types of packages that can exist.

Packages in Fedora Core or Fedora Extras
Fedora RPM Name Original Package Name Actual Version RPM Revision
foobar-1.2.3-0.1.beta1 foobar-1.2.3beta1.tar.gz 1.2.3 beta 1 1
foobar-1.2.3-1 foobar-1.2.3.tar.gz 1.2.3 final 1

Local Modifications to Upstream Packages
Local RPM Name Upstream RPM Name Actual Version RPM Revision
foobar-1.2.3-0.1.beta1.ed.1 foobar-1.2.3-0.1.beta1 1.2.3 beta 1 1
foobar-1.2.3-1.ed.1 foobar-1.2.3-1 1.2.3 final 1

Packages Not Upstream Packaged Locally
Local RPM Name Original Package Name Actual Version RPM Revision
foobar-1.2.3-0.ed.0.1.beta1 foobar-1.2.3beta1.tar.gz 1.2.3 beta 1 1
foobar-1.2.3-0.ed.1 foobar-1.2.3.tar.gz 1.2.3 final 1

Packages From Third Party Repositories
Local RPM Name Original Package Name Third Party RPM Name Actual Version RPM Revision
foobar-1.2.3-0.ed.0.1.beta1 foobar-1.2.3beta1.tar.gz foobar-1.2.3-0.beta1.1.fc3.fr 1.2.3 beta 1 1
foobar-1.2.3-0.ed.1 foobar-1.2.3.tar.gz foobar-1.2.3-1.1.fc3.fr 1.2.3 final 1


TODO Notes

Points to comment on specifically:

  • Define upstream.
  • Explicitly state upstream repositories that the DICE Packgage Naming Guidelines are compatile with.
  • Note the impotance of %{name}-%{version} matching exactly for package to be considered a revision of an upstream package.
  • Describe what to do in the case when foobar-1.2.3-0.1.beta1 exists upstream and we want to ship foobar-1.2.3 final locally, i.e. should we ship foobar-1.2.3-0.ed.1 or a foobar-1.2.3-0.1.beta1.ed.1 that is modified/patched to be the final release?

Other Package Naming Related Resources

Response to Feedback

Two issues relating to Package Naming were highlighted at the Infrastructure meeting on 2005-03-08:

  • Allowing for downstream packages.
  • Options/Alternatives to the proposed naming.

Allowing for downstream packages

I've thought this through and it can be done within the current naming framework. I did have this in mind when designing the naming but had not explicity stated anything about this in the document to prevent further confusion. As you add more levels of repositories (dice, ed, lcfg are in some respects at the same level - i.e. a single entity controls them all) the compatability issues with upstream become more complex. In general you can simply add on yet another suffix for downstream local modifications. The problem area is downstream local packages that could then appear in any of the upstream repositories - the 0. prefix hack isn't always guaranteed to work beyond base + 1.

Essentially for everything to work properly in this respect for arbitrary levels, each "organisational level" of repositories needs some marker that will always be overriden by upstream, "0" being the most common for base +1. As soon as you go beyond base +1 you end up with very convoluted release tags. To properly allow abritrary "organaisational level" prioritisation using the %{release} tag every level needs to agree on a priority marker within the release. One of the problems here is that "base" (Fedora/RH) isn't part of such and agreement - we have to work around what their have in their %{release}.

This problem really should be fixed using repository prioritisation at the package management tool level, not by overloading the release tag.

Options/Alternatives to the proposed naming

When I said that there is not much room to maneuver what I meant was any modification is really just a variation on a theme - essentially syntactic variation. The semantics of what's going on are pretty much defined by how RPM does version comparisons. Where there is room to change things a bit is with the versioning of packages that we consider unlikely to ever go upstream, e.g. you could make 0.lcfg.7 7.lcfg or lcfg.7 - this would then allow the 0. hack to be used by downstream repositories for these packages. The downside to this is that you add another branch into the decision tree and remove some of the consistency in the naming, essentially introducing two naming schemes at each level.

Topic revision: r19 - 15 Apr 2005 - 00:30:38 - CarwynEdwards
 
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
This Wiki uses Cookies