From Fedora Project Wiki
DocsProject Header docTeam1.png


Upstream Versioning Recommendation (Draft)

This text tries to communicate to upstream projects about implications of different kind of software versioning schemes from downstream point of view.

While listing the schemes that cause more workload and attention in downstream, it also gives a recommendation that should work for most of the upstreams and is harmless and straight forward in downstream point of view.


Note.png
Document role
Note that this is only a recommendation and its role is only informal.

Motivation

Some versioning schemes need extra attention while packaging them into distribution. If a package maintainer fails to do that, future upstream releases may have versions that break automatic package upgrade path.

When successfull, all this extra workload and attention is lost work hours and away from more productive distribution work, causes extra package builds in build system (equals to loss of computing power, storage and electricity) even may cause problems for end users. Thus all of it should be avoided if possible.

Anatomy of RPM Version

describe it here, complete nevr and make it simple


Ugly Workarounds

If and a packager fails to convert the upstream version into correct version+release combination in distribution, that forces packager to use an Epoch tag:

Warning.png
Quote: Use of Epochs
The Epoch tag in RPM is to be used only as a last resort, and should be avoided whenever possible. However, it is sometimes necessary to use an Epoch to handle upstream versioning changes or to ease transition from third party repositories.

Use of Epoch is irrevocable decision for package whole lifespan and causes even more attention in future package updates.


Problematic Cases

While Packaging Guidelines describes these cases in great detail, here we outline an abstract of the issue. The main source of the problems is non-numeric symbols in version. There are three cases when these are typically used:

  • pre-release versions
  • snapshot versions
  • post-release versions

In these cases, Packaging Guidelines describe how these string parts in version may have to be moved into package Release Tag.

Optimal Schemes

Projects should avoid using non-numerical versions.

list examples with different major + minor combinations

list examples of projects which tackle different releases (pre-, snap-, post) without non-numeric parts