Skip to content
This repository has been archived by the owner on Feb 3, 2022. It is now read-only.

VersionNumbers

Jump to bottom
Robert M. Lefkowitz edited this page Jun 23, 2014 · 7 revisions

Table of Contents

Platform version numbers

This page describes how the version numbers for the platform work and why we do it this way.

These are the important points to keep in mind when considering schemes for version numbers:

  • We have two major releases per year
  • Minor releases are API compatible
  • We have testing pre-releases for each major release
  • We follow the Haskell Package Versioning Policy (PVP)

The Haskell Platform concept calls for major and minor releases.

  • The point of major releases is to update the set of common packages we all use. That is, to specify which packages and which versions (corresponding to APIs). The target is to have major releases every 6 months.
  • The point of minor releases is to support a major release across a range of operating systems over time and respond to bugs that are discovered in a library or tool subsequent to their release. The target is to have 2-3 minor releases after major releases at intervals on the order of 4-6 weeks.

The policy decision agreed on the libraries mailing list is that minor (or patch-level) release must not change the exported API of any library packages and that the platform as a whole must follow the PVP.

Examples

  • 2010.1.0.0, 2010.1.1.0, ... testing pre-releases for the first major release of the year
  • 2010.2.0.0: first major release in 2010.
  • 2010.2.0.1: minor bug fix release, compatible with 2010.2.0.0
  • 2010.3.0.0, 2010.3.1.0, ... testing pre-releases for the second major release
  • 2010.4.0.0: second major release in 2010.
  • 2010.4.0.1: minor bug fix release, compatible with 2010.4.0.0

The general scheme for stable releases

$year . $major-release . 0 . $minor-version

Together, the $year and $major-release identify the major version.

When the $major-release is even, it's a stable release. Minor (or patch-level) releases within a stable release have exactly the same API. Only bug fixes are allowed in patch-level releases.

When the $major-release is odd, it's a testing pre-release. Minor releases are fresh testing snapshots. There is no API compatibility guarantee.

Rationale

We need to be able to distinguish major from minor releases. So we cannot simply use the date.

We need to give version numbers to pre-releases because we need to get wide testing from developers/users, so being able to track and identify pre-releases is important.

The version scheme should follow the PVP and should reflect the fact that it is the union of its components. Since minor releases may not change API at all then this dictates that only the 4th digit changes. The 3rd digit remains at 0 because there are never any API-compatible additions in a minor release.

Alternatives

One alternative that fits the requirements is a monitonically increasing major version number, like 20.x for a major release and 20.0, 20.1, etc for minor releases. This is what GNOME uses.

FAQ

  • Q: Are pre-releases API compatible with the final release?
A: No, there is no such guarantee for testing pre-releases. Only minor stable releases are guaranteed to be API compatible with the previous minor releases in the same major release series. In practice we expect there to be an API freese some weeks before the major release, so that testers have time to check the whole thing works without there being constant API churn.
  • Q: Should the pre-release for 2010.2.0 be called 2010.1.x even if it's still 2009?
A: Yes, the current date does not matter. It's the target release date that matters. It should be called 2010.1.x, not something like 2009.5.x.
  • Q: Why not use a monitonically increasing major version number? Why use the year?
A: Because it makes it clear that it is a never a finished project, and that we do time-based rather than feature based releases. It also tells you slightly more information (e.g. you can quickly tell how out-of-date your distro's support is).
  • Q: Why is there a redundant 0 as the third digit?
A: Because that is what is required for the platform to follow the Package Versioning Policy (PVP). Since minor releases do not change the API at all, then the PVP dictates that we bump the 4th digit, not the 3rd. The 3rd is reserved for compatible API additions.
  • Q: Why did the first 2009.2.0 release not use a 4th digit like 2009.2.0.0?
A: Because the decision to follow the PVP was made after 2009.2.0 had already been released.
Clone this wiki locally