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

[Tim Hudson]

I think we have to keep OPENSSL_VERSON_NUMBER and it has to have
MAJOR.MINOR.FIX in it encoded as we currently have it (where FIX is PATCH
in semantic terms and our current alpha PATCH is left blank).
That is what I've been saying in the various emails - because we precisely
need to not change the definition of what that macro is - as people
interpret it.
I suggest we zero out all the other information in the
OPENSSL_VERSION_NUMBER macro.
And I did also suggest we make the OPENSSL_VERSION_TEXT field precisely
what semantic versioning would have us do - and either drop the things we
have that don't fit or encode them following the rules.

I would also suggest we make that macro up using macros that use the
semantic version terminology directly.
i.e. something like the following.

And the version number is encoded that way to not break the existing usage
(except that what we currently call a fix is actually semantically named a
patch).
One of the critically important parts of semantic versioning is that the
API is precisely only about the major.minor.patch.

The examples for pre-release and build-metadata are just showing that one
goes first with a hyphen and can have dot separated things, the other goes
second with a plus and also can have dot separated things.
If we wanted to keep the date concept in the version text macro then we
encode it correctly - or we can stop doing that sort of thing and leave it
out.
The pre-release can be blank. The build metadata can be blank.

In semantic versioning terms this is what it would mean.
And if you want to check release/alpha/beta status you look at the
OPENSSL_VERSION_PRE_RELEASE macro and we stop the release+alpha+beta
indicator usage in the OPENSSL_VERSION_NUMBER macro.
It was rather limiting in its encoding format. That more rightly belongs in
the semantic version string format.

#include <stdio.h>

#define OPENSSL_MSTR_HELPER(x) #x
#define OPENSSL_MSTR(x) OPENSSL_MSTR_HELPER(x)

#define OPENSSL_VERSION_MAJOR  1
#define OPENSSL_VERSION_MINOR   1
#define OPENSSL_VERSION_PATCH   2
#define OPENSSL_VERSION_PRE_RELEASE "-beta1.special"
#define OPENSSL_VERSION_BUILD_METADATA "+21Sep2018.optbuild.arm"

#define OPENSSL_VERSION_NUMBER
(long)((OPENSSL_VERSION_MAJOR<<28)|(OPENSSL_VERSION_MINOR<<20)|(OPENSSL_VERSION_PATCH<<12))
#define OPENSSL_VERSION_TEXT OPENSSL_MSTR(OPENSSL_VERSION_MAJOR) "."
OPENSSL_MSTR(OPENSSL_VERSION_MINOR) "." OPENSSL_MSTR(OPENSSL_VERSION_PATCH)
OPENSSL_VERSION_PRE_RELEASE OPENSSL_VERSION_BUILD_METADATA

int main(void)
{
  printf("0x%8lx\n",OPENSSL_VERSION_NUMBER);

printf("%d.%d.%d\n",OPENSSL_VERSION_MAJOR,OPENSSL_VERSION_MINOR,OPENSSL_VERSION_PATCH);
  printf("%s\n",OPENSSL_VERSION_TEXT);
}

And the output you get:

0x10102000
1.1.2
1.1.2-beta1+21Sep2018.optbuild.arm

Tim.



On Fri, Sep 21, 2018 at 11:36 PM Richard Levitte <levitte at openssl.org>
wrote:

> In message <CAHEJ-S7Uww84Np+JhWYgTZ26Eo7oszK+y=
> w2o_njr8bFOorsmw at mail.gmail.com> on Fri, 21 Sep 2018 23:01:03 +1000, Tim
> Hudson <tjh at cryptsoft.com> said:
>
> > Semantic versioning is about a consistent concept of version handling.
> >
> > And that concept of consistency should be in a forms of the version
> > - be it text string or numberic.
> >
> > That you see them as two somewhat independent concepts isn't
> > something I support or thing makes sense at all.
>
> In that case, we should probably just thrown away
> OPENSSL_VERSION_NUMBER and come up with a different name.  If we keep
> that macro around, it needs to be consistent with its semantics as
> we've done it since that FAQ update.  Otherwise, I fear we're making
> life much harder on those who want to use it for pre-processing, and
> those who want to check the encoded version number.
>
> I do get what you're after...  a clean 1:1 mapping between the version
> number in text form and in numeric encoding.  I get that.  The trouble
> is the incompatibilities that introduces, and I'm trying to take the
> middle ground.
>
> > Our users code checks version information using the integer
> representation and it should be in
> > semantic form as such - i.e. the pure numeric parts of the semantic
> version.
> >
> > This is the major point I've been trying to get across. Semantic
> versioning isn't about just one
> > identifier in text format - it is about how you handle versioning in
> general. And consistency is its
> > purpose.
>
> Sure.
>
> Would you mind writing up a quick proposal on a new encoding of the
> version?  (and just so you don't limit yourself too much, it's fine by
> me if that includes abandoning the macro OPENSSL_VERSION_NUMBER and
> inventing a new one, a better one, with a definition that we can keep
> more consistent than our current mess)
>
> Cheers,
> Richard
>
> --
> Richard Levitte         levitte at openssl.org
> OpenSSL Project         http://www.openssl.org/~levitte/
> _______________________________________________
> openssl-project mailing list
> openssl-project at openssl.org
> https://mta.openssl.org/mailman/listinfo/openssl-project
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mta.openssl.org/pipermail/openssl-project/attachments/20180922/7016c778/attachment-0001.html>