User:Tibbs/TildeVersioning: Difference between revisions

Latest revision as of 16:25, 26 November 2018

Notes for the tilde versioning drafts

There are two drafts:

User:Tibbs/TildeVersioning1 allows tilde and moves prerelease snapshot information into the Version: tag.
User:Tibbs/TildeVersioning2 allows tilde but prohibits its use with prerelease snapshots.
User:Tibbs/TildeCaretVersioning allows both tilde and caret versioning to keep Release: completely free of versioning information. Caret versioning comes from https://github.com/rpm-software-management/rpm/pull/597.

Neither of the first two drafts is as simple as the current guidelines but the second is a relatively small addition. I don't know if either is more acceptable to anyone in particular. The third draft, on the other hand, is a significant simplification. It has been merged into upstream RPM, and maybe it will be backported to the live Fedora branches afterwards. Even if it is, the question of RHEL/EPEL will remain. We can hope.

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 at odds with each other if all we have is the tilde operator:

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

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, 1.2.1-1 + Epoch)

So that won't work. Pushing snapshot information into release just gives us the current guidelines.

You can try to throw a tilde in there:

(1.2-1, 1.2+0~20180101.abcde-1, 1.2.1-1)

It works in that case but sadly it breaks if 1.2a is released instead of 1.2.1.

So it seems we have no choice but to keep putting post-release snapshot information into Release: or wait until we can use the caret operator.

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 absolutely terrible 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~20180101.1.beta1) (tack a counter onto the date)

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

(1.2-1.20180101.abcde or 1.2-0.1.20190101.abcde, ???)

Unless you use a tilde with nothing (which sort of mirrors what I've done with the full tilde-caret guidelines)

(1.2~-1.20180101.abcde, 1.2~beta1-1)

What to do?

I see five options:

Don't change anything.
Allow tilde and 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.
Allow tilde. Keep post-release snapshot information in Release:. Keep prerelease snapshot information in Version.
Allow tilde, with post-release info in Release and prerelease info in a place decided by whether you ever intend to package snapshots.
Wait for the implementation of caret to be merged and pushed back to live Fedora branches.

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.

The fifth option permits some really clean guidelines, but we have to wait a bit (maybe three weeks) and then EPEL cannot follow.

One thing is clear: allowing tilde by itself 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. If we have both tilde and caret then things get significantly simplified.

@@ Line 1: / Line 1: @@
-{{DISPLAYTITLE:Guidelines for Versioning Fedora Packages}}
+== Notes for the tilde versioning drafts ==
-<div style="float: right; margin-left: 0.5em" class="toclimit-2">__TOC__</div>
-In Fedora, the package versioning scheme (which encompasses both the <code>Version:</code> and <code>Release:</code> tags, as well as <code>Epoch:</code>) balances two separate goals:
+There are two drafts:
+* [[User:Tibbs/TildeVersioning1]] allows tilde and moves prerelease snapshot information into the Version: tag.
+* [[User:Tibbs/TildeVersioning2]] allows tilde but prohibits its use with prerelease snapshots.
+* [[User:Tibbs/TildeCaretVersioning]] allows both tilde and caret versioning to keep Release: completely free of versioning information.  Caret versioning comes from https://github.com/rpm-software-management/rpm/pull/597.
-* To provide information about the version of the packaged software to users.  When a package version does not correspond directly to the upstream version of the software, some useful information is conveyed such as the date a snapshot was taken or whether a pre- or post-release version has been packaged.
+Neither of the first two drafts is as simple as the current guidelines but the second is a relatively small addition.  I don't know if either is more acceptable to anyone in particular.
+The third draft, on the other hand, is a significant simplification.  It has been merged into upstream RPM, and maybe it will be backported to the live Fedora branches afterwards.  Even if it is, the question of RHEL/EPEL will remain.  We can hope.
-* To ensure proper ordering between updates to a package within a Fedora release, as well as between Fedora releases.  Within a release, Fedora does not allow package versions to go backwards, so the versioning scheme must produce successive versions which increase monotonically, even if the upstream versions don't have this property when compared using RPM's version comparison function.  The versioning scheme also ensures that for a package built at the same time for two different Fedora releases, the version in the newer release sorts higher than the version in the older release.
+The fundamental issues I'm trying to solve:
-Fedora's versioning scheme must adapt to whatever scheme any upstream developer may choose for versioning their software, while at the same time preserving the two goals above.
+* 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.
-The <code>Epoch:</code> tag, which provides the most significant input to RPM's version comparison function, SHOULD ONLY be used or incremented when necessary to avoid ordering issues.  If present, it MUST contain a positive integer.  <code>Epoch:</code> MUST NOT ever be decreased in any way.
+With that in mind, here's the problem: these two simple, common cases are at odds with each other if all we have is the tilde operator:
+* Moving from a post-release snapshot to a new version.
+* Moving between upstream tagged prereleases and git snapshots.
-== Some definitions ==
+=== Moving between post-release snapshots and tagged releases ===
-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.
+Take this version sequence:
+* (1.2, git snapshot, 1.2.1)
-;release version
+Current guidelines give:
-: A version of the software which upstream has decided to release.  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.
+* (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, 1.2.1-1 + Epoch)
+So that won't work.  Pushing snapshot information into release just gives us the current guidelines.
-;snapshot
+You can try to throw a tilde in there:
-: An archive taken from upstream's source code control system which is not associated with any release version.
+* (1.2-1, 1.2+0~20180101.abcde-1, 1.2.1-1)
+It works in that case but sadly it breaks if 1.2a is released instead of 1.2.1.
-;prerelease version
+So  it seems we have no choice but to keep putting post-release snapshot information into Release: or wait until we can use the caret operator.
-: 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 release of that version has not yet been made.  These we call prerelease versions.  Any snapshots made while upstream is preparing for their release are also considered prerelease versions.
-;postrelease version
+=== Moving between tagged prereleases and git snapshots ===
-: Any version which happens after a particular release is technically "post-release", but before upstream begins making prereleases for the next version, any snapshot is considered a postrelease version.
-;non-sorting version sequence
+Take this 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.
+* (1.2beta1, git snapshot, 1.2beta2, git snapshot, 1.2)
-== Examples ==
+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 absolutely terrible but it seems that #1 is the simplest that allows tilde.  I'm calling the third one the "post-prerelease snapshot" option.
-Examples of many possible versioning scenarios are available from [[Package Versioning Examples]].
+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)
-== Simple versioning ==
+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~20180101.1.beta1) (tack a counter onto the date)
+With snapshot information in release, you can't add the beta1 tag anywhere.
+* (1.2-1.20180101.abcde or 1.2-0.1.20190101.abcde, ???)
+Unless you use a tilde with nothing (which sort of mirrors what I've done with the full tilde-caret guidelines)
+* (1.2~-1.20180101.abcde, 1.2~beta1-1)
-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.
+=== What to do? ===
-This is a very common versioning scheme, and the vast majority of software projects use something which works like this.
+I see five options:
-To package '''release versions''' of software using this versioning scheme:
+# Don't change anything.
-* Use the upstream verbatim in the <code>Version:</code> tag.  Don't trim leading zeroes.
+# Allow tilde and 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.
-* Use a <code>Release:</code> tag starting with 1 (never 0).  Append the [[Packaging:DistTag|Dist tag]].  Increment the release (by 1) for each update you make.  Reset to 1 whenever you change <code>Version:</code>.
+# Allow tilde. Keep post-release snapshot information in Release:.  Keep prerelease snapshot information in Version.
+# Allow tilde, with post-release info in Release and prerelease info in a place decided by whether you ever intend to package snapshots.
+# Wait for the implementation of caret to be merged and pushed back to live Fedora branches.
-== More complex versioning ==
+Since people have declared that the first option is simply something they will ignore because they want tilde so much.
-There are several ways in which the simple scheme might not work in a particular situation:
+The second option just seems unreasonable.
-* Upstream has never chosen a version; only snapshots are available for packaging.
+The third option seems... inconsistent but at least possible to describe.
-* 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.
-* You need to apply a small fix to a release branch of Fedora without updating the newer branches.
-* 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 potentially removing some information from the <code>Version:</code> tag while imposing additional structure onto the <code>Release:</code> tag.  There are potentially three fields which comprise the structured <code>Release:</code> tag:
+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.
-* package release number (<code><pkgrel></code>)
+The fifth option permits some really clean guidelines, but we have to wait a bit (maybe three weeks) and then EPEL cannot follow.
-* extra version information (<code><extraver></code>)
-* snapshot information (<code><snapinfo></code>)
-* minor release bump (<code><minorbump></code>)
-The package release number MUST always be present while the others may or may not be depending on the situation.
+One thing is clear: allowing tilde by itself 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.  If we have both tilde and caret then things get significantly simplified.
-Those items which are present are combined (with periods to separate them) to construct the final <code>Release:</code> tag.  In the usual notation where square brackets indicate that an item is optional:
-* <code><pkgrel>[.<extraver>][.<snapinfo>]%{?dist}[.<minorbump>]</code>
-The actual values to be used for those three fields are situational and are referenced in the sections below.  Note that your particular situation might not result in the use of <code><extraver></code> or <code><snapinfo></code>, and in most situations <code><minorbump></code> won't be used at all.  Simply do not include those which you don't have.
-=== Upstream has never chosen a version ===
-When upstream has never chosen a version, you MUST use <code>Version: 0</code>.  "<code>0</code>" sorts lower than any other possible value that upstream might choose.  And if upstream does choose to release "version 0" then you can immediately move to using <code>Release: 1%{?dist}</code> with no ordering issues.
-=== Upstream uses invalid characters in the version ===
-It's possible that upstream uses characters besides ASCII letters (upper and lower case), digits and periods 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.
-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.
-=== Unsortable versions ===
-When upstream uses a versioning scheme that does not sort properly, first see if there is any portion which can be removed from the right side of the version string such that the remainder is sortable.  This is often possible if upstream uses a sequence like ("1.2pre1", "1.2pre1", "1.2final"). If so, use the removed portion as "extra version information" above, and the remainder as the package version.  If this splitting left a leading or trailing periods from either value, remove them.
-If this is not possible, use Version: 0 and move the _entire_ version string into "extra version information".
-=== Snapshots ===
-All snapshots MUST contain a snapshot information field (<code><snapinfo></code>) in the <code>Release:</code> 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:
-* <code>YYYYMMDD.<revision></code>
-* <code>YYYYMMDD<scm><revision></code>
-Where <code><scm></code> is a short string identifying the source code control system upstream uses (e.g. "git", "svn", "hg") or the string "snap".  <code><revision></code> 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 ===
-In the <code>Version:</code> tag, use the version that upstream has determined the next release will be.  For the <code><pkgrel></code> field of the <code>Release:</code> tag, use a number of the form "0.N" where N is an integer beginning with 1 and increasing for each revision of the package.  Prerelease versions MUST use a <code>Release:</code> tag strictly less than 1, as this is the sole indicator that a prerelease has been packaged.
-=== Release and post-release versions ===
-For the <code><pkgrel></code> field of the <code>Release:</code> tag, use an integer beginning with 1 and increasing for each revision of the package.  Release and post-release versions MUST use a <code>Release:</code> 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 <code>Epoch:</code> tag, or to begin using it by adding <code>Epoch: 1</code>.  At the same time, try to work with upstream to hopefully minimize the need to involve <code>Epoch:</code> in the future.
-=== You need to 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 pkg = 1.0-1%{?dist} in F{{FedoraVersionNumber|previous}} and F{{FedoraVersionNumber|current}}, and only F{{FedoraVersionNumber|previous}} needs a fix. Normally, you would need to bump the release in each of the branches to ensure that F{{FedoraVersionNumber|previous}} < F{{FedoraVersionNumber|current}}, but that is a waste of time and energy for the newer branches which do not need to be touched.
-In this case, you MAY set <code><minorbump</code> to an in integer beginning with '1' and increasing by one for each minor bump you need to do.  Remove <code><minorbump></code> once you are able to increase the package release normally without introducing ordering issues.
-== 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.

Search