On Sat, 22 Sep. 2018, 3:24 am Viktor Dukhovni, <openssl-us...@dukhovni.org> wrote:
> > On Sep 21, 2018, at 12:50 PM, Tim Hudson <t...@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 <https://www.openssl.org/blog/blog/2018/09/11/release111/> 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 <https://github.com/openssl/openssl/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 <https://github.com/openssl/openssl/commit/093f5d2c152489dd7733dcbb68cbf654988a496c> which is when 1.0.0 started. Saying that our documentation in doc/crypto/OPENSSL_VERSION_NUMBER.pod <https://github.com/openssl/openssl/blob/master/doc/man3/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 <https://github.com/openssl/openssl/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 <https://www.openssl.org/policies/releasestrat.html> 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 <https://en.wikipedia.org/wiki/OpenSSL> 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.
_______________________________________________ openssl-project mailing list openssl-project@openssl.org https://mta.openssl.org/mailman/listinfo/openssl-project
