0

We use semantic versioning. Suppose we have some software release with a version number of e.g. 2.1.1. Because of an API change the next release has version number 3.0.0. Now let us suppose that a bug is found which occurs both in version 2.1.1 and version 3.0.0. Since some customers still use 2.1.1 and we do not want to force them to upgrade to a version 3.0.1 or later we provide a maintainance (bug fix) release for version 2.1.1. A straight forward version number for this release could be 2.1.2. Though no such example is given in the defintion of precedence I would conclude that the rules imply 2.1.2 < 3.0.0 - meaning what? Version 2.1.2 was released after 3.0.0 and version 3.0.0 does not include all bug fixes of 2.1.2. Actually these two versions are not really orderable, the versions (and the corresponding source revisions) now have a tree structure:

  |
2.1.1        (1)
  |\
  | \
  | 2.1.2    (3)
  |
3.0.0        (2)
  |

To reflect that tree structure and avoid confusion I would prefer a version number scheme like the following:

  |
2.1.1        (1)
  |\
  | \
  | 2.1.1+m  (3)
  |
3.0.0        (2)
  |

(+m for maintainance release). According to the definition of precedence in semantic versioning this would still imply 2.1.1+m < 3.0.0, but for our customers we could add a rule that for x1.y1.z1 < x2.y2.z2 any version x1.y1.z1+m* is not comparable to x2.y2.z2 (but x1.y1.z1 < x2.y2.z2+m* still holds).

Are there any best practices for versioning a tree structure? Or did I get something wrong about semantic versioning?

coproc
  • 6,027
  • 2
  • 20
  • 31

1 Answers1

1

No, you should not assume any release date ordering from semver precedence relations such as 2.1.2 < 3.0.0. All you can determine is that there probably have been be breaking changes between them.

If you want build date information, that would be reasonable to include in the build metadata, but that metadata has absolutely nothing to do with the semver concept of precedence. However a human might reasonably conclude that version 2.1.2+201706010005 was probably built after 3.0.0+201603151112.

Burt_Harris
  • 6,415
  • 2
  • 29
  • 64
  • So given the precedence `2.1.2 < 3.0.0`, what may I assume? I think that it is reasonable to assume that all work done for `2.1.2` is incorporated into `3.0.0`. (see also the image to the right at en.wikipedia.org/wiki/Software_versioning#Sequence-based_identifiers) Only in exceptional cases this will not hold. Adding a timestamp goes into this direction, but I would prefer a scheme that makes these exceptional cases more explicit. (e.g. only add `+...` to a version if the general assumption is not valid) – coproc Jun 01 '17 at 08:26
  • What I'm saying is that, under the rules of semantic versioning (which applies to the public API of a package) that's not ___semver reasonable___. – Burt_Harris Jun 01 '17 at 15:17
  • Many publishers choose to implement a versioning schema that implies different standards of reasoning than semver. That's perfectly OK, but there should be no confusion in what contexts the semver rules of reasoning apply. For example, proper operation of the `npm` package manager **requires** that semantic versioning be applied. – Burt_Harris Jun 01 '17 at 15:23
  • Ok, so I am not alone thinking that semver 2.0.0 does not cover all aspects of versioning ... – coproc Jun 02 '17 at 08:15
  • Btw: I think now that point 11 of semver 2.0.0 specification (definition of "precedence") is superfluous and does not add anything useful. The "precedence" as defined in semver 2.0.0 only tells you, when you can put a `<` between two versions, but does not give any meaning to it. Funny oversight ... – coproc Jun 02 '17 at 08:16
  • 1
    With other release information (e.g. release notes), semver ranges spanning major version might be meaningful. Lets say I use package `x`, which in version 1.4 introduced a feature `good` I need. Sometime later, version 2.0 is released due to a breaking removing some other feature named `bad`. I don't know if `good` will be around in a hypothetical version 3, so I can say I'm compatible with `x@>=1.4<3.0` – Burt_Harris Jun 05 '17 at 15:16