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

Fri Sep 21 12:52:37 UTC 2018

In message <CAHEJ-S7nvqYLRevEnX11_vCaiyq7mw85yX+5VPYwW0Bcuv_VzQ at mail.gmail.com> on Fri, 21 Sep 2018 20:48:34 +1000, Tim Hudson <tjh at cryptsoft.com> said:

> On Fri, Sep 21, 2018 at 7:58 PM Richard Levitte <levitte at openssl.org> wrote:
> 
>  Our FAQ says that such changes *may* be part of a major
>  release (we don't guarantee that breaking changes won't happen), while
>  semantic versioning says that major releases *do* incur backward
>  incompatible API changes.
> 
> I think you are misreading the semantic versioning usage - it states
> when things MUST happen. It does not state that you MUST NOT change
> a version if the trigger event has not occurred.

Fair point...  so OK, we're then even more compatible with semver than
I though.

> Semantic versioning also requires you to explicitly declare what
> your public API is in a "precise and comprehensive" manner.
> What do you consider the public API of OpenSSL?

The collection of stuff in our public headers, i.e. all headers that
we end up installing in {prefix}/include/openssl.

I thought we all agreed on that.  If we don't, then we need to discuss
that as well...  in a different thread.

> That is pretty much a prerequisite for actually adopting semantic
> versioning.

> I also think the concept of reinterpreting the current major version
> number into an epoch as you propose is not something that we should
> be doing.

The way we've been changing the version number and the way we describe
our current version number scheme in the FAQ (since 2012, but this had
already happened in spirit before that), that first 1 Is Not The Major
Version Number.  It's just a 1 that sits there with no real purpose
any more.  Last time it served as a major version number was when we
released 1.0.0.  In my mind, that 1 needs to go away.

Do you want me to pull out the full history lesson?  You know I can.

So the say we current do things, the version number is
1.MAJOR.MINORfix-letter, and I'm trying to change that to
MAJOR.MINOR.PATCH, where PATCH takes the role we have currently
assigned to letters.

Note that this is for the text form, which is separate from our
numeric encoding (something that isn't covered by semver at all).
That is the only place where I propose to have an epoch, and it's for
one purpose only, that the value of that number should be greater in
the next version number.  If it wasn't for that, I would drop it
entirely and just have 0 in its place in the number, i.e. the proposed
2.0.0 would be encoded to 0x00200000L (formalised encoding would then
be 0x0MMNNFFSL).

> We have defined the first digit as our major version number - and
> changing that in my view at least would be going completely against
> the principles of semantic versioning.
> The version itself is meant to be purely X.Y.Z[-PRERELEASE] or
> X.Y.Z[+BUILDMETA] and your suggested encoding is not that at all.
> 
> What you have is EPOCH.X.Y.Z.FIX.STATUS - where EPOCH and STATUS are
> not concepts contained within semantic versioning.

I don't know how you got that into so many numbers.  In 0xEMMNNFFSL,
you have Epoch(E), Major(X), miNor(Y), Fix(Z) and Status(S).  With Fix
already finding a place in Z, I dunno why you need another FIX, and I
have no idea why you want the status (prerelease number) to not be
separated from the rest of the version with a dash.

I'll repeat this again: semantic version Does Not Talk About Numeric
Encoding At All.  It only covers text.  Numeric encoding is *entirely*
left to us, so we're entirely free to only use MM, NN, FF and S,
becoming MM.NN.FF-S (translating to semver X.Y.Z-STATUS).

In my proposal, the epoch is silent in the text / semantic form of the
version number.

But OK, I get the message, I need to flesh out the document a bit
more.

> Basically adopting semantic versioning actually requires something
> different to what has been proposed in my view.
> 
> I would suggest it means our current version encoding in an integer
> of MNNFFPPS becomes simply MNNFF000 and the information for PP and S
> is moved elsewhere as semantic versioning defines those concepts
> differently (as noted above).

Just let me hammer in yet again that the numeric encoding is out of
scope re semantic versioning, we're free to do what the hell we want,
including have a *silent* epoch that simply doesn't show in the text
form version.

> Part of our challenge is ensuring we don't cause unnecessary
> breakage for users:
> 
> Vendors change the text string to add additional indicators for
> their variations.
> Otherwise developers use the current integer version for feature
> testing - and it needs to remain compatible enough.

And that, especially the last part is exactly what I'm trying to
accomplish.  Your proposed change of the encoded number to 0xMNNFF000L
makes it incompatible.

> I haven't seen any code actually testing the S field within the
> version or doing anything specific with the PP version - other than
> reporting it to the user.

OpenSSH did check the full number for a while, at least during the
0.9.6 series (and I suspect all the 0.9.x versions).  They did that
because we broken API compatibility in the middle of 0.9.6.  This I
know for fact.  Actually, they still do, but after 1.0.0, only what
they have perceived as major version (including what my proposal calls
the epoch):

https://github.com/openssh/openssh-portable/blob/master/openbsd-compat/openssl-compat.c#L42-L67

So basically, they don't trust us to do shared library version bumping
right yet...  and all things considered, that's fair.

Cheers,
Richard

-- 
Richard Levitte         levitte at openssl.org
OpenSSL Project         http://www.openssl.org/~levitte/