RPM Packaging guidelines

TODO.

See https://xcp-ng.org/forum/topic/183/git-repository-structure-and-conventions-for-rpms until we've got something better.

Release tag

The Release tag versions the packaging itself (whereas the Version tag is the version of the software that we package).

It is usually reset to value 1 when the Version is increased, then incremented at each build of the same Version. Adding patches to a RPM does not modify the Version, only the Release.

The Release is suffixed with %{?dist}, which is replaced at build time by .xcpngX.Y (for example .xcpng8.2 for XCP-ng 8.2). There is one, unique, exception: xcp-ng-release does not have this suffix, because it is the first RPM built for any release, and is the one that provides each subsequently built RPM with the value with which %{?dist} is to be replaced.

The "increment the release when you rebuild" rule has exceptions, detailed below.

Source RPMs initially coming from an upstream source

For packages that initially come from XenServer, CentOS or another provenance of source RPMs, and which we rebuild or patch, we increment the release by less than one, using what is called a "subrelease". The objective is that our Release does not conflict with any future package released upstream.

Example:

• Release for a source RPM coming from an upstream source: 3%{?dist}. Several situations:
  • We rebuild it as is, without touching the spec file at all: we keep 3%{?dist}. As %{?dist} will be evaluated as xcpngX.Y, our build will not be mistaken for an upstream build.
  • We modify it before rebuilding (addition of patches, packaging changes...): we increment the subrelease, not the release, so the Release becomes 3.1%{?dist}.

If the upstream source RPM already uses the subrelease (e.g.: Release: 9.1.4%{?dist}), we go one digit further (e.g.: Release: 9.1.4.1%{?dist}). Said differently: we never increase existing numbers, we add our own instead.

Another rule related to packages based on upstream source RPMs: if the Release tag is missing the %{?dist} suffix, we add it.

Test builds and alternate builds

Often, we will need to do test builds of existing packages.

Say that our distro has a somepackage package, which has the following builds in XCP-ng 8.2:

• base repository (tag v8.2-base in koji):
  • somepackage-1.0-2.xcpng8.2
• updates repository (tag v8.2-updates in koji):
  • somepackage-1.0-3.xcpng8.2 (an update with a patch that fixes a security issue)
  • somepackage-1.1-1.xcpng8.2 (a bugfix update that incremented the version number to 1.1)
  • somepackage-1.1-2.xcpng8.2 (another security patch some time after that)

Now, we would like to do a new build, so we need to increment the release, and we may be unsure how to increment it exactly.

It depends on the situation and on the goals.

• If this is meant to be the next official update, we simply increment the Release (or the subrelease if our package is based on an upstream source RPM, see section above): the current release is 2%{?dist} so we set it to 3%{?dist}. Then we submit the build to the v8.2-testing target in koji, and package named somepackage-1.1-3.xcpng8.2 will appear in the testing RPM repository.
• If this is an experimental/beta package that adds features that we want users of the stable release of XCP-ng to be able to test, we will then choose our Release carefully in order to not conflict with future official updates. So, if the current release is 2%{?dist}, we will set ours to 2.0.awesomestuff.1%{?dist} and then increment the last digit in subsequent builds. This way, we guarantee that our test package will always be considered older than any future official update to the same package. We will then submit our build either to v8.2-testing or to another appropriate target in koji. Maybe the v8.2-awesomestuff target was created for this experiment (associated with an awesomestuff RPM repository on mirrors), so we will use it to avoid interfering with v8.2-testing which is made for update candidates.