[openssl-project] A proposal for an updated OpenSSL version scheme (v2)

Sat Sep 22 04:59:02 UTC 2018

This was a lot.

Can I start with asking that we stop referring to enigmatic users?
They are diverse and so are their views on this (if not just utter
confusion when they can't make sense of how our version numbers
change...  The Wikipedia article may be reflection of that, or it
might be that its authors are smarter than us).

The message I get from all of this -- *and this is something I agree
with* -- is that we've treated the semantics of our version number
wrong ever since 1.0.0 was released, or at least since that FAQ entry
came up.  Or to put it differently, our actions and how we have talked
about major releases and minor / feature releases don't match the
documentation in opensslv.h comment and in pod on how our versioning
works.

I also get the message that semantic versioning per se is good and
that we actually have something close according to documentation.  I
have not seen anyone saying that we shouldn't go with semantic
versioning, even though we may have different views on timing.

It seems to me that this boils down to a disagreement over
technicalities, how to use OPENSSL_VERSION_NUMBER, what bits to look
at to figure out compatibility with what the application was built
against.
(this reminded me that there are those who dlopen libcrypto and libssl
rather than linking with it at build time...  it makes sense to
compare numbers in that case)

So in summary, do we agree on this, and that it's a good path forward?

- semantic versioning scheme good, we should adopt it.
- we need to agree on how to translate that in code.
- we need to stop fighting about history.

Cheers,
Richard

In message <CAHEJ-S6f33iJbH-HbDc5iBx_k0ehdOsJBOH49RmZRE1Q6roSZg at mail.gmail.com> on Sat, 22 Sep 2018 11:28:44 +1000, Tim Hudson <tjh at cryptsoft.com> said:

> On Sat, 22 Sep. 2018, 3:24 am Viktor Dukhovni, <openssl-users at dukhovni.org> wrote:
> 
>  > On Sep 21, 2018, at 12:50 PM, Tim Hudson <tjh at cryptsoft.com> wrote:
>  > If that is the case then our current practice of allowing ABI breakage with
>  > minor release changes (the middle number we document as the minor release number)
>  > has to change.
>  CORRECTION: As advertised when 1.0.0 first came out, and repeated in our release
>  policy:
>  As of release 1.0.0 the OpenSSL versioning scheme was improved
>  to better meet developers' and vendors' expectations. Letter
>  releases, such as 1.0.2a, exclusively contain bug and security
>  fixes and no new features. Minor releases that change the
>  last digit, e.g. 1.1.0 vs. 1.1.1, can and are likely to
>  contain new features, but in a way that does not break binary
>  compatibility. This means that an application compiled and
>  dynamically linked with 1.1.0 does not need to be recompiled
>  when the shared library is updated to 1.1.1. It should be
>  noted that some features are transparent to the application
>  such as the maximum negotiated TLS version and cipher suites,
>  performance improvements and so on. There is no need to
>  recompile applications to benefit from these features.
> 
> I have to disagree here. We said things about minor releases and major releases but we didn't say
> things about the version numbers or change the documentation or code comments to say the first
> digit was meaningless and that we have shifted the definition of what X.Y.Z means.
> 
> That parsing of history I think is at best a stretch and not supportable and also not what our users
> think.
> 
> Our users don't call 1.0.2 the 0.2 release of OpenSSL. Our users don't call 1.0.0 the 0.0 release.
> There isn't a short hand or acceptance or a decision communicated to conceptually drop the 1. off
> the front of our versioning.
> Your logic and practice is saying you see the first two digits as the major version number - that's
> fine - you are welcome to take an ABI compatible short hand to refer to version - but that doesn't
> mean we changed the definition of our versioning system.
> What you are tracking there is effectively the SHLIB version.
> 
> So if our users don't think that, and our code comments don't stay that, and our pod
> documentation doesn't say that and users have the first part in their masks and don't just ignore it
> then I don't think it is supportable to claim we told everyone it was a meaningless first digit and
> changed our definition of our versioning scheme back at the 1.0.0 release.
> 
> Currently when we make minor API changes that aren't breaking we update the fix version
> number. When we make major API changes which we expect to be breaking we update the minor
> version number.
> Now think about the transition from 1.1.0 to 1.1.1 - that is by any reasonable definition a major
> release - but we don't update the major version number by either definition of the major version
> number.
> We call it in our website a "feature release" - yet more terminology to dance around our version
> numbering scheme.
> Read the actual blog post and try to parse that as a minor release - it isn't - it is a major
> release - but we did not change the major release number even if we accepted the theory and
> your definition that the first number is meaningless and it is only the second number that is the
> real major version and the third number isn't a fix version is it actually the minor version. The
> implications of that view point aren't supported by our actions.
> 
> We did not say we are redefining the concept of our release numbering scheme - we just defined
> what API impacts there were and we used "major" and "minor" about release efforts and
> impacts - not about changing the definition of the parts of the OPENSSL_VERSION_NUMBER
> macro and the corresponding meaning of what SSLeay_version_num() and now
> OpenSSL_version_num() returns. This is a core part of our API.
> 
> Remember that SSLeay_version_num() was only renamed OpenSSL_version_num() in 2015 in
> commit b0700d2c8de79252ba605748a075cf2e5d670da1 as part of 1.1.0
> The first update for the top nibble indicating the major version number had changed was back in
> 2009 in commit 093f5d2c152489dd7733dcbb68cbf654988a496c which is when 1.0.0 started.
> 
> Saying that our documentation in doc/crypto/OPENSSL_VERSION_NUMBER.pod was just forgotten
> to be updated and happens to be wrong (in order to support that view point) isn't matched by the
> actual update history - it was updated in 2014 in commit
> 9208640a36228b10fcdf75c8853d9410aaff19a3 and it actually changed the documentation of
> what the major version number encoding is - from the top two nibbles to just the top nibble. If your
> assertions about the history were accurate then I would expect to see a comment there that the
> top nibble is a meaningless epoch and the major version is encoded elsewhere. But what was done
> there was to bring the documentation in line with the code comment and also in line with
> reality and what our users perceive things as.
> 
>  The 2nd/3rd nibbles in OPENSSL_VERSION_NUMBER are not "the minor version number",
>  they are just some bits in an ordinal.
> 
> Our documentation says otherwise. Our code comments say otherwise. Our users (I assert) say
> otherwise.
> And your rationale for this in the website statements in their plain reading also support that - you
> have to insert "number" in quite a few places in order to read the context of those posts as
> meaning we have a change in the encoding scheme for numbers.
> We didn't do that.
> 
> So in summary, don't mix major and minor in the sense of the scope of a change in with the major
> version number and minor version number - that is I think where the confusion comes from in
> terms of your interpretation (and Richard's proposal).
> We did not explicitly disconnect those concepts from their encoding in
> OPENSSL_VERSION_NUMBER, we did not redefine what we meant by version.
> We also did not say the first two digits are the major version number and the next digit is the
> minor version number.
> 
> One of those two leaps has to be made to support your view point and I see no evidence to
> actually support that without inserting meaning into the release strategy that isn't actually there
> and conflicts with multiple other sources of information.
> Remember our users read the code and sometimes the documentation when using OpenSSL - a
> user doesn't go and read our release strategy to see if there is some wording that happens to have
> updated meaning.
> 
> And for amusement value, I reference the "ultimate source of truth" - our entry on Wikipedia
> which lists our "major version releases" using the same sort of loose release effort scope definition
> with no connection to the major version number.
> For wikipedia, all major.minor.fix releases are "major version releases" - and that I think actually
> matches our users view point.
> 
> Tim.
> 