User:Tibbs/TildeVersioning

This is a revised draft, which additionally removes snapshot info from Release:. The previous draft was shown to be unworkable in practice as required the introduction of Epoch: in a relatively common version sequence.

Fedora's package versioning scheme encompasses both the Version: and Release: tags, as well as Epoch:). The overriding goal is to provide sequence of packages which are treated as updates by RPM's version comparison algorithm while accommodating varied and often inconsistent upstream versioning schemes.

Notes for this draft

This section isn't part of the main guidelines; I just need a place to put notes.

The fundamental issues I'm trying to solve:

• People really want to use tilde because for some (limited but common) cases it makes things simpler.
• We need something which is relatively simple and "works" for the range of problems generally seen by people.
• It would be nice to be prescriptive for weirder cases.
• Keeping Release: simple is really appealing.

With that in mind, here's the problem: these two simple, common cases are hard in general:

• Moving between upstream tagged prereleases and git snapshots.
• Moving from a post-release snapshot to a new version.

Moving between tagged prereleases and git snapshots

Take this version sequence:

• (1.2beta1, git snapshot, 1.2beta2, git snapshot, 1.2)

Current guidelines give:

• (1.2-0.1.beta1, 1.2-0.2.20180101.abcde-1, 1.2-0.3.beta2, 1.2-0.3.20180102.fghij-1, 1.2-1) (0)

With keeping Release: pristine, you have to insert a digit and it's simplest to just start when you introduce a snapshot:

• (1.2~beta1-1, 1.2~1.20180101.abcde-1, 1.2~2.beta2-1, 1.2~3.20180102.fghij-1, 1.2-1) (1)

Not inserting the digit until necessary does work, but seems easy to get wrong and hard to describe:

• (1.2~beta1-1, 1.2~20180101.abcde-1, 1.2~3.beta2-1 ???, 1.2~4.20180102.fghij-1, 1.2-1) (2)

Pushing the snapshot information into Release gives:

• (1.2~beta1-1, 1.2~beta1-2.20180101.abcde, 1.2~beta2-1, 1.2~beta2-2.20180102.fghij, 1.2-1) (3)

Now, to me none of these look particularly bad but it seems that #1 is the simplest that allows tilde. I'm calling the third one the "post-prerelease snapshot" option.

What if you knew upstream was going to put out 1.2 and package a snapshot, but then upstream releases a beta?

• (1.2 git snapshot, 1.2beta1)

Current guidelines of course work fine:

• (1.2-0.1.20180101.abcde, 1.2-0.2.beta1)

Keeping "pristine Release" with requiring the extra digit on snapshots works:

• (1.2~1.20180101.abcde, 1.2~2.beta1)

Without the requirement for the digit on snapshots it "works" but is less pleasant:

• (1.2~20180101.abcde, 1.2~3.beta1)

With snapshot information in release, you can't add the beta1 tag anywhere.

• (1.2-1.20180101.abcde, ???) or (1.2-20180101.abcde, ???)

Moving between post-release snapshots and tagged releases

Take this version sequence:

• (1.2, git snapshot, 1.2.1)

Current guidelines give:

• (1.2-1, 1.2-2.20180101.abcde, 1.2.1-1)

Keeping Release: pristine sounds great, but....

• (1.2-1, 1.2+20180101.abcde, 1.2.1-1 + Epoch)

So push snapshot information into Release:

• (1.2-1, 1.2-2.20180101.abcde, 1.2.1-1)

So obviously, uh, we have no choice but to keep our current Release: mangling here.

If we had some magical operator ':' or something which compared like this: (1.2-1 < 1.2:20180101.abcde < 1.2.1-1) then life would be golden, but I don't think it exists.

What to do?

I see four options:

1. Don't change anything.
2. Allow tilde but keep snapshot information in Release:. Requires the odd "post-prerelease snapshot" thing if you ever go from a snapshot to a prerelease. Forbid the packaging of tagged prereleases if prerelease snapshots for the same version were packaged.
3. Allow tilde. Keep post-release snapshot information in Release:. Keep prerelease snapshot information in Version.
4. Allow tilde, with post-release info in Release and prerelease info in a place decided by whether you ever intend to package snapshots.

Since people have declared that the first option is simply something they will ignore because they want tilde so much.

The second option just seems unreasonable.

The third option seems... inconsistent but at least possible to describe.

The fourth option is simply insane, but seems to be what the people who want tilde say because it appears they don't ever intend to package prerelease snapshots and don't care about that use case.

One thing is clear: allowing tilde does not simplify the guidelines. It does make some specific versioning cases look nicer. When you completely ignore the existence of snapshots, tilde certainly makes loads of sense.

Some definitions

Note that upstreams may each have their own terminology and it is in general impossible to define these terms with complete generality. For some upstreams, every commit is itself considered a version. Many upstreams never make releases, instead just letting users take whatever is in the code repository at any given time.

release version

A version of the software which upstream has decided give a version and call "released". The act of releasing the software can be as simple as adding a git tag. This includes so-called "point releases" or "patchlevels" which some upstreams make, since those are actually assigned versions and released, but it doesn't include so called "prerelease versions".

prerelease version

Before a release happens, many upstreams will decide which version that will release will have, and then produce "alphas", "betas", "release candidates", or the like which carry that new version but indicate that the final release of that version has not yet been made. These we call prerelease versions. The importance is that upstream is basically "counting down" towards some version number. Fedora needs to indicate that, but needs to make sure that the ordering is correct so that the Fedora package will properly upgrade to that version when it is actually released.

postrelease version

Any version which upstream doesn't call a release which happens after a particular release but before upsteam decides to make a "prerelease". The distinction is that with a prerelease, upstream has made some decision about what to call the next version. With a postrelease they haven't, and Fedora can't pick something for them. Note that if tags, makes a tarball or even issues a patch file called "patchlevel1" or something like that, it's not considered a postrelease. It's just a release.

snapshot

An archive taken from upstream's source code control system which is not equivalent to any release version.

non-sorting version sequence

A sequence of version strings which is not ordered in the same way that RPM's version comparison function would order it. RPM has a somewhat complicated version comparison function which it will use to determine if a package is "newer". If upstream's idea of what constitutes a "newer" version differs from RPM's implementation then simply using upstream's versions directly will result in updates which don't actually update any packages because to RPM they look "older".

Examples

Examples of many possible versioning scenarios and tips on making your own version comparison tests are available from Package Versioning Examples.

Epoch: tag

The Epoch: tag provides the most significant input to RPM's version comparison function. If present, it MUST consist of a positive integer. It SHOULD ONLY be introduced or incremented when necessary to avoid ordering issues. The Epoch: tag, once introduced to a package, MUST NOT ever remove or be decreased in any way.

Simple versioning

Most upstream versioning schemes are "simple"; they generate versions like "1.2.03.007p1". They consists of one or more version components, separated by periods. Each component is a whole number, potentially with leading zeroes. The rightmost component can also include one or more ASCII letters, upper or lower case. The value of a component must *never* be reduced (to a value which sorts lower) without a component somewhere to the left increasing. Note that the version sequence ("1.4a", "1.4b", "1.4") does not meet this criterion, as "4" sorts lower than "4b". The sequence ("1.4", "1.4a", "1.4b") is, however, simple.

This is a very common versioning scheme, and the vast majority of software projects use something which works like this.

To package release versions of software using this versioning scheme:

• Use the upstream in the Version: tag. Don't trim leading zeroes.
• Use a Release: tag that contains a positive integer, beginning with 1.
  • Increment it for each change made to the package which does not change Version:.
  • Reset to 1 when Version: changes.

If upstream uses a version containing dashes it usually suffices to either remove them or convert them to periods or underscores to get a simple versioning scheme. See #Upstream uses invalid characters in the version below.

More complex versioning

There are several ways in which the simple scheme might not work in a particular situation:

• Upstream has never chosen a version; only snapshots are available for packaging.
• Upstream simply doesn't use a version scheme which orders properly under RPM's version comparison operation.
• You wish to package a prerelease version (snapshot or otherwise).
• You wish to package a postrelease snapshot.
• Upstream was thought to be following one scheme but then changed in a way that can't be sorted.
• More than one of the above may apply (lucky you). Follow all of the relevant recommendations below together.

The methods for dealing with most of these issues involves tag while imposing additional structure onto the Version: tag. There are potentially four fields which comprise the structured Version: tag:

• Upstream release version (<upstreamrel>)
• Upstream prerelease identifier (<upstreamprerel>)
• an integer introduced to impose a sort order when necessary (<sort>)
• snapshot information (<snapinfo>)
• an integer incremented for each Fedora release and reset for version changes (<fedorarel>)

Those items which are present are combined to construct the final Version:-Release: combination in one of the following forms. The usual convention where items in square brackets might not be present applies.

• <upstreamrel>~[<sort>.]<upsteamprerel>-<fedorarel> (for prerelease versions)
• <upstreamrel>~[<sort>.]<snapinfo>-<fedorarel> (for prerelease snapshots)
• <upstreamrel>-<fedorarel>.<snapinfo> (for postrelease snapshots)

A tilde ('~') indicates a prerelease; RPM will compare a string containing a tilde as being less (or older) than the equivalent string with the tilde and the content following it removed.

The actual values to be used for those fields are given in the sections below.

The <sort> field

It can sometimes become necessary to insert an integer into the Version: in one place to ensure that RPM orders things properly. This can happen if upstream's prerelease versions don't sort, or if you switch between packaging an actual prerelease version and a snapshot. We want to avoid introducing Epoch: if at all possible, so the <sort> field is used instead.

When you need to "introduce <sort>", just set it to 1 and start using it as above. It will always be followed by a period. <sort> will generally go away when <upstreamrel> changes, or (in the case of prereleases) <upstreamrel> is actually released.

Snapshots

All snapshots MUST contain a snapshot information field (<snapinfo>) in the Version: tag. That field must at minimum consist of the date in eight-digit "YYYYMMDD" format. The packager MAY include up to 17 characters of additional information after the date. The following formats are suggested:

• YYYYMMDD.<revision>
• YYYYMMDD<scm><revision>

Where <scm> is a short string identifying the source code control system upstream uses (e.g. "git", "svn", "hg") or the string "snap". <revision> is either a short git commit hash, a subversion revision number, or something else useful in identifying the precise revision in upstream's source code control system. Obviously if CVS is used, no such revision information exists, so it would be omitted, but otherwise it SHOULD be included.

Prerelease versions

This is where the bulk of the tilde-related changes will be.
Instead of using a simple Version: tag and overloading <pkgrel>, instead pkgrel stays simple and Version: gets the complexity. There are two options here: one which forces the use of an integer to force sortability of the prerelease information. The other leaves it optional. I've gone for the optional route because the general case looks cleaner, but this isn't my proposal so....

In the Version: tag, use the following construction: <nextversion>~<prerelease>. That is a literal tilde ( ~) which instructs RPM to sort this Version: immediately before a package with the same version but no tilde.

• <nextversion> should contain the version which upstream has decided this line of development will become once it has been released.
• <prerelease> should contain a string which upstream has chosen to version the prereleases in this line of development. Usually this will be something like "alpha3" or "pre2", and may need to be altered such that it includes no invalid characters. (See above.)

Note that values for <prerelease> must form a sortable sequence. If you are not sure that your upstream will maintain sortability, you can form <prerelease> by prepending a positive integer: <integer>.<unsortable>.

Release and post-release versions

For the <pkgrel> field of the Release: tag, use an integer beginning with 1 and increasing for each revision of the package. Release and post-release versions MUST use a Release: tag greater than or equal to 1.

Upstream makes unsortable changes

It is possible that upstream simply adopts a different versioning scheme, fails to follow an expected pattern, or even simply resets their version to some lower value. If none of the above operations can help with giving a version which sorts properly, or give you a version which simply sorts lower than the packages already in Fedora, then you have little recourse but to increment the Epoch: tag, or to begin using it by adding Epoch: 1. At the same time, try to work with upstream to hopefully minimize the need to involve Epoch: in the future.

Upstream has never chosen a version

When upstream has never chosen a version, you MUST use 0 for <upstreamrel> and otherwise follow the guidelines for prerelease snapshots. "0" sorts lower than any other possible value that upstream might choose. And if upstream does choose to release "version 0.1" (or "0.0.1" or something similar) then you can immediately move to using Version: 0.1 and Release: 1%{?dist} with no ordering issues.

Upstream uses invalid characters in the version

It's possible that upstream uses characters besides digits, ASCII letters (upper and lower case), periods and underscores in its version. They must be removed and potentially replaced with valid characters. Any such alterations MUST be documented in the specfile. It is not possible to cover all potential situations here, so it is left to the packager to alter the upstream versioning scheme consistently. It is common, however, to either remove dashes or replace them with underscores or periods (which RPM treats identically).

After altering the version to be free of invalid characters, see #Unsortable versions below if the modifications, when applied to successive releases from upstream, will not order properly. It is, however, often the case that a simple modification will give a scheme appropriate for #Simple versioning.

Rawhide is allowed to lag temporarily

A package MAY temporarily have a lower EVR in Rawhide when compared to a release branch of Fedora ONLY in the case where the package fails to build in Rawhide. This permits important updates to be pushed to existing Fedora releases regardless of the current state of Rawhide.

Making a change an old branch without rebuilding the others

Sometimes, you may find yourself in a situation where an older branch needs a fix, but the newer branches are fine. For example, if you have Release: 3%{?dist} in F28 and F29, and only F28 needs a fix. Normally, you would need to bump the release in each of the branches to ensure that F28 < F29, but that is a waste of time and energy for the newer branches which do not need to be touched. ple In this case, you MAY append an integer to the very end of Release:, after the dist tag. For the above example, you would use Release: 3%{?dist}.1. This integer MUST begin at '1' increase by one for each minor bump you need to do. Remove this integer once you are able to increase the package release normally without introducing ordering issues.