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

2018-09-21 Thread Tim Hudson
On Sat, Sep 22, 2018 at 3:12 PM Viktor Dukhovni 
wrote:

> The proposal to move the minor version into nibbles 2 and 3 breaks this
> OpenSSH function.
>

No it doesn't - because I'm not talking about moving *anything* in the
current encoding for major and minor - see earlier post.
The positions don't change for minor version. We just stop using the
current PATCH and use the current FIX as PATCH.
And the logical test there remains valid in that it detects all
incompatible versions correctly - what changes is that some versions that
are compatible are seen as incompatible - but that is an incorrect
interpretation that is *safe.*

And note that the openssh code there is actually more conservative than it
needs to be already.

And under semantic versioning, it is only the MAJOR that changes when
breaking changes happen.

But what I've been referring to is that there is other code that uses our
documented encoding and parses it ... this isn't just an openssh issue.

Tim
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

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

2018-09-21 Thread Tim Hudson
If you accept that we have a MAJOR.MINOR.FIX.PATCH encoding currently
documented and in place and that the encoding in OPENSSL_VERSION_NUMBER is
documented then the semantic versioning is an easy change.
We do not need to change our encoding of MAJOR.MINOR - that is documented
and fixed. We just need to start using it the way semantic versioning says
we should.
We need to eliminate FIX - there is no such concept in semantic versioning.
And PATCH exists as a concept but in semantic versioning terms it is a
number.

That leads to two main choices in our current encoding as to how we achieve
that:
1) leave old FIX blank
2) move old PATCH to old FIX and leave old PATCH blank (i.e. old FIX is
renamed to new PATCH and old PATCH is eliminated)

Option 2 offers the *least surprise* to users - in that it is how most
users already think of OpenSSL in terms of a stable API - i.e. our current
MAJOR.MINOR.FIX is actually read as MAJOR.MINOR.PATCH or to be more precise
our users see FIX and PATCH as combined things - they don't see our MAJOR
and MINOR as combined things.

Under option 2 it does mean anyone that thinks a change of our current
MINOR means an ABI break would be interpreting things incorrectly - but
that interpretation is *entirely safe* - in that they would be assuming
something more conservative rather than less conservative. And leaving the
old PATCH blank doesn't hurt anyone.

I don't think that moving to semantic versioning requires us to change our
encoding of OPENSSL_VERSION_NUMBER except to move PATCH to FIX - as one of
those concepts disappears.
And then when we do a major release update (like 1.1.1) we end up with a
MAJOR version change.

Alternatively, we can elect to effectively say the OPENSSL_VERSION_NUMBER
encoding we have documented and supported is subject to yet another change
where we reinterpret things.
That is doable - but I also think entirely unnecessary and confusing for
our users.

Tim
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

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

2018-09-21 Thread Viktor Dukhovni



> On Sep 22, 2018, at 12:50 AM, Tim Hudson  wrote:
> 
> The impact of the breaking change on anyone actually following our documented 
> encoding cannot.
> i.e. openssh as one example Richard pointed out.

The only use of OPENSSL_VERSION_NUMBER bits in OpenSSH (which is not yet ported 
to
1.1.x upstream BTW, so hardly relevant really) is:

ssh_compatible_openssl(long headerver, long libver)
{
long mask, hfix, lfix;

/* exact match is always OK */
if (headerver == libver)
return 1;

/* for versions < 1.0.0, major,minor,fix,status must match */
if (headerver < 0x100f) {
mask = 0xf00fL; /* major,minor,fix,status */
return (headerver & mask) == (libver & mask);
}

/*
 * For versions >= 1.0.0, major,minor,status must match and library
 * fix version must be equal to or newer than the header.
 */
mask = 0xffffL; /* major,minor,status */
hfix = (headerver & 0x000ff000) >> 12;
lfix = (libver & 0x000ff000) >> 12;
if ( (headerver & mask) == (libver & mask) && lfix >= hfix)
return 1;
return 0;
}

all other uses as a simple ordinal.  In the above function they expect
stability of the ABI for matching first three nibbles and release
status.  Which makes a case for Richard's encoding scheme as being
more compatible with one of the more prominent applications that depends
on the encoding.

The proposal to move the minor version into nibbles 2 and 3 breaks this
OpenSSH function.

-- 
Viktor.

___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Viktor Dukhovni



> On Sep 22, 2018, at 12:59 AM, Richard Levitte  wrote:
> 
> 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.

Yes.

-- 
Viktor.

___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Richard Levitte
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  
on Sat, 22 Sep 2018 11:28:44 +1000, Tim Hudson  said:

> On Sat, 22 Sep. 2018, 3:24 am Viktor Dukhovni,  
> wrote:
> 
>  > On Sep 21, 2018, at 12:50 PM, Tim Hudson  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 

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

2018-09-21 Thread Tim Hudson
On Sat, Sep 22, 2018 at 11:55 AM Viktor Dukhovni 
wrote:

> this is an ad-hoc encoding with monitonicity as the
> the only constraint.
>

If you start from the position that the encoding of OPENSSL_VERSION_NUMBER
is free to change so long as the resulting value is larger than what we
have been using for all previous versions then a whole range of options
come into play.
But we shouldn't assert that we aren't changing the meaning of
OPENSSL_VERSION_NUMBER - and that is what others have been doing on this
thread - and what your previous email also asserted.

It is a *breaking* change in our comments and our documentation and in what
our users are expecting. Basically it is an API and ABI change - we said
what the number means and we are changing that.
The impact of the breaking change for those using it for pure feature
testing for API difference handling (where it isn't actually parsed) can be
minimised just by always having a larger number that all previous uses.
The impact of the breaking change on anyone actually following our
documented encoding cannot.
i.e. openssh

as
one example Richard pointed out.
That isn't the only code that actually believes our header files and
documentation :-)

Semantic versioning is about MAJOR.MINOR.PATCH with specific meanings.
There is no FIX concept as such. There is PRERELEASE and METADATA.
One of our existing concepts disappears - we have MAJOR.MINOR.FIX.PATCH
currently and we also encode STATUS as a concept (which we can map mostly
to PRERELEASE).

And if we are changing to fit into semantic versioning we need to use its
concepts and naming and not our present ones.
A merge of concepts pretty much goes against the point of semantic
versioning.

Tim.
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

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

2018-09-21 Thread Viktor Dukhovni
> On Sep 21, 2018, at 9:28 PM, Tim Hudson  wrote:
> 
> That parsing of history I think is at best a stretch and not supportable and 
> also not what our users think.

This isn't a mathematical theorem or even a legal debate.
We should do what makes the most sense going forward.

Richar proposes, and I agree that it makes more sense to leave room for
two nibbles of major number, and that for better or worse applications
expect to see the same top 3 nibbles in a given stable ABI.

The proposal to lose many of the low bits in the ordinal, and lose
the status bits, ... is just not appealing, and there is no API/ABI
reason to retain the verbatim mapping from notional major/minor/micro/...
into the ordinal, this is an ad-hoc encoding with monitonicity as the
the only constraint.

I don't agree that anything about semantic versioning, or our past
practice constrains the encoding beyond that sole constraint.  So
I'm afraid there are no arguments that will convince me that what
appears to be a less flexible encoding is somehow a forced choice.

We'll have to disagree on this one, and see where the consensus
falls.

-- 
Viktor.

___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Tim Hudson
On Sat, 22 Sep. 2018, 3:24 am Viktor Dukhovni, 
wrote:

> > On Sep 21, 2018, at 12:50 PM, Tim Hudson  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

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

2018-09-21 Thread Viktor Dukhovni



> On Sep 21, 2018, at 4:55 PM, Richard Levitte  wrote:
> 
> I think we need to get rid of OPENSSL_VERSION_NUMBER.

Absolutely not.  That's the one thing we must keep, and keep monotone
so that applications continue to compile and build.

Sure we need to communicate our ABI/API stability policies, and publish
release numbers and all that, but the API must provide a sensible
backwards compatible macro for testing whether the compile-time
version exceeds various threshold values.

We should also provide various helper macros, but NOT remove the
legacy encoded number.  That's a non-starter.

-- 
Viktor.

___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Viktor Dukhovni



> On Sep 21, 2018, at 12:14 PM, Matt Caswell  wrote:
> 
> I support Richard's proposal with an epoch of 1.
> Grudgingly I would accept an epoch in the 3-8 range.
> I would oppose an epoch of 2.

I can live with that, though it might mean that a minority of
applications will interpret (based on obsolete nibble extraction)
that OpenSSL 2.0.0 (0x102FUL) is actually OpenSSL 1.2.0, but
that's probably harmless.  It does mean we might never reclaim the
version numbers with 0x2 for the high nibble.

-- 
Viktor.

___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Matt Caswell



On 21/09/18 17:04, Viktor Dukhovni wrote:
> I think I've said everything I have to say on this topic.  So I'll stop
> for now.  I continue to support Richard's proposal, but with an epoch
> smaller than 8.
> 

To summarise my position:

I support Richard's proposal with an epoch of 1.
Grudgingly I would accept an epoch in the 3-8 range.
I would oppose an epoch of 2.

Matt
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Viktor Dukhovni
> On Sep 21, 2018, at 11:56 AM, Tim Hudson  wrote:
> 
> What I was suggesting is that we don't need to break the current encoding at 
> all.

Not changing the encoding has a downside.

 * The bits that represent ABI stability would shift from the
   2nd/3rd nibbles to just the first nibble.

 * We lose the option of changing the encoding in the future unless
   we start requiring 64-bit longs.

 * We end up with 3 status nibbles, two of which some applications
   may misinterpret as holding a patch level:

0xUL

On the whole maintaining the current placement of the major number in
the encoding makes it less not more natural for holding the new semantic
versions in a backwards-compatible way.

I think I've said everything I have to say on this topic.  So I'll stop
for now.  I continue to support Richard's proposal, but with an epoch
smaller than 8.

-- 
Viktor.

___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Tim Hudson
On Sat, Sep 22, 2018 at 1:39 AM Viktor Dukhovni 
wrote:
>  The only change needed is a minor one in applications that actually
> parse the nibbles

What I was suggesting is that we don't need to break the current encoding
at all.
We have a major.minor.fix version encoded and documented in the header file
that we can continue to represent in semantic terms.
So anyone decoding those items will actually get the correct result (from a
user perspective).
Those using it for conditional compilation checks continue to work.

BTW thanks for the correction on "a" to "1" for the patch release (wasn't
being careful there).

Tim.
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

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

2018-09-21 Thread Viktor Dukhovni



> On Sep 21, 2018, at 11:40 AM, Tim Hudson  wrote:
> 
> That is something I wouldn't suggest makes sense as an approach - to change 
> the tarfile name and leave all the internals the same achieves nothing.

And that's not the proposal.  The proposal is that the new major number
is 2 (or 3 if someone sees a compelling need to skip over LibreSSL),
changing not just the marketing name but also the internal version.

The *integer* representing the combined major.minor.micro (+ status)
is not a data structure.  Its encoding has changed multiple times
over the years, and will now change once more, in a way that preserves
order.  That's all.  We'll just need to update:

  https://www.openssl.org/docs/manmaster/man3/OPENSSL_VERSION_NUMBER.html

to indicate a new encoding as of 0x2000UL and up.

-- 
Viktor.

___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Tim Hudson
On Sat, Sep 22, 2018 at 1:34 AM Matthias St. Pierre <
matthias.st.pie...@ncp-e.com> wrote:

>
> On 21.09.2018 17:27, Tim Hudson wrote:
> >
> > We cannot remove the current major version number - as that concept
> exists and we have used it all along.
> > We don't just get to tell our users for the last 20+ years what we
> called the major version (which was 0 for the first half and 1 for the
> second half) doesn't exist.
> >
>
> There has been a famous precedent in history though:  Java dropped the
> "1." prefix when going from "1.4" to "5.0"
> (https://en.wikipedia.org/wiki/Java_version_history#Versioning_change)
>

Unfortunately that isn't a good example - as the version number didn't
actually change - just the marketing and download packaging.
The APIs continue to return 1.5.0 etc.
And many Java developers continue to use the real version numbers.

That is something I wouldn't suggest makes sense as an approach - to change
the tarfile name and leave all the internals the same achieves nothing.

Tim.
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

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

2018-09-21 Thread Viktor Dukhovni



> On Sep 21, 2018, at 11:27 AM, Tim Hudson  wrote:
> 
> No it isn't - as you note that isn't a valid mapping - 1.0 isn't a semantic 
> version and there is no such thing as a fix number,
> You get three concepts and then on top of that the pre-release and the 
> build-metadata.
> 
> Semantic versioning is about the API not the ABI.
> 
> So we could redefine what we have been telling our user all along and combine 
> our current major+minor in a new major version.
> Making 1.0.2a be 10.2.0 in semantic version terms.

Now that we've agreed on the semantic minor number, it is easy to note that 
1.0.2a's
micro number is "1" not 0, since the .0 release with 1.0.2 (no letter).  As for
the major number being "10", that's silly, we can just subtract 8, and land on
2 which is the next major number value we've not used.  There's no reason to 
jump
to 10.

> We cannot remove the current major version number - as that concept exists
> and we have used it all along.

And it can now become "2".

> We don't just get to tell our users for the last 20+ years what we called the
> major version (which was 0 for the first half and 1 for the second half) 
> doesn't
> exist.

It still exists, it becomes 2.  And an "epoch nibble" of 0x2 in 
OPENSSL_VERSION_NUMBER
maintains proper ordering.  The users see a sane versioning scheme, that is
backwards compatible.  You seem to be somewhat fixated (pardon the language,
no disrespect intended) on some unnecessary constraint.  The encoding:

0x2UL

just works to represent semantic version MM.NN.FF with  == 0xF for
final release, and 0x0--0xE for pre-releases.  There is no disruption.
The only change needed is a minor one in applications that actually
parse the nibbles, ... most don't, they just use the version number
as an ordinal for conditional compilation.

-- 
Viktor.

___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Matthias St. Pierre

On 21.09.2018 17:27, Tim Hudson wrote:
>
> We cannot remove the current major version number - as that concept exists 
> and we have used it all along. 
> We don't just get to tell our users for the last 20+ years what we called the 
> major version (which was 0 for the first half and 1 for the second half) 
> doesn't exist.
>

There has been a famous precedent in history though:  Java dropped the "1." 
prefix when going from "1.4" to "5.0"
(https://en.wikipedia.org/wiki/Java_version_history#Versioning_change)

Matthias


___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

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

2018-09-21 Thread Tim Hudson
On Sat, Sep 22, 2018 at 1:16 AM Viktor Dukhovni 
wrote:

>
>
> > On Sep 21, 2018, at 11:00 AM, Tim Hudson  wrote:
> >
> > If you repeat that in semantic versioning concepts just using the labels
> for mapping you get:
> > - what is the major version number - the answer is clearly "1".
> > - what is the minor version number - the answer is clearly "0"
> > - what is the fix version number - there is no such thing
> > - what is the patch version number - the answer is clearly "2" (reusing
> the fix version)
>
> I'm afraid that's where you're simply wrong.  Ever since 1.0.0, OpenSSL
> has promised (and I think delivered) ABI stability for the *minor* version
> and feature stability (bug fixes only) for the patch letters.  Therefore,
> the semantic version number of "1.0.2a" is "1.0", its minor number is 2
> and its fix number is 1 ("a").
>

No it isn't - as you note that isn't a valid mapping - 1.0 isn't a semantic
version and there is no such thing as a fix number,
You get three concepts and then on top of that the pre-release and the
build-metadata.

Semantic versioning is about the API not the ABI.

So we could redefine what we have been telling our user all along and
combine our current major+minor in a new major version.
Making 1.0.2a be 10.2.0 in semantic version terms.

We cannot remove the current major version number - as that concept exists
and we have used it all along.
We don't just get to tell our users for the last 20+ years what we called
the major version (which was 0 for the first half and 1 for the second
half) doesn't exist.

Tim.
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

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

2018-09-21 Thread Viktor Dukhovni



> On Sep 21, 2018, at 11:16 AM, Viktor Dukhovni  
> wrote:
> 
> I'm afraid that's where you're simply wrong.  Ever since 1.0.0, OpenSSL
> has promised (and I think delivered) ABI stability for the *minor* version
> and feature stability (bug fixes only) for the patch letters.  Therefore,
> the semantic version number of "1.0.2a" is "1.0", its minor number is 2
> and its fix number is 1 ("a").
> 
> Now of course "1.0" is not a valid semantic version number, but fortunately,
> we've since released "1.1" and are now considering "1.2" which with semantic
> versioning, is ready to become simply "2" as the "1." prefix is not needed,
> and "2" is conveniently larger than the current "not-really major" leading 
> "1".

To clarify, in the above I said "semantic version number" a few times where
I meant to say "semantic major version number"...

-- 
Viktor.

___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Viktor Dukhovni



> On Sep 21, 2018, at 11:13 AM, Matthias St. Pierre 
>  wrote:
> 
> I like Richard's approach (with the '8' or another number) and  I don't think 
> it is
> contradicting semantic versioning. Maybe a good compromise between  your two
> opposing views would be to make the encoding irrelevant to our users by 
> introducing
> version check macros like
> 
>OPENSSL_MAKE_VERSION(maj,min,patch)and
>OPENSSL_VERSION_AT_LEAST(maj,min)
> 
> (note: the patch level was omitted from the second macro on purpose)
> 
> which enable the application programmer to write code like
> 
> 
> #if OPENSSL_MAKE_VERSION(2,0,0) <= OPENSSL_VERSION_NUMBER
> ...
> #endif

The macros would help new software, and should be added, but existing
software should continue to work with the version-dependent bits
unmodified.  To that end, Richard's encoding does the job (modulo a
minor quibble over the high bit vs. just an epoch nibble of 0x2 or 0x3).

-- 
Viktor.

___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Viktor Dukhovni



> On Sep 21, 2018, at 11:00 AM, Tim Hudson  wrote:
> 
> If you repeat that in semantic versioning concepts just using the labels for 
> mapping you get:
> - what is the major version number - the answer is clearly "1".
> - what is the minor version number - the answer is clearly "0"
> - what is the fix version number - there is no such thing
> - what is the patch version number - the answer is clearly "2" (reusing the 
> fix version)

I'm afraid that's where you're simply wrong.  Ever since 1.0.0, OpenSSL
has promised (and I think delivered) ABI stability for the *minor* version
and feature stability (bug fixes only) for the patch letters.  Therefore,
the semantic version number of "1.0.2a" is "1.0", its minor number is 2
and its fix number is 1 ("a").

Now of course "1.0" is not a valid semantic version number, but fortunately,
we've since released "1.1" and are now considering "1.2" which with semantic
versioning, is ready to become simply "2" as the "1." prefix is not needed,
and "2" is conveniently larger than the current "not-really major" leading "1".

> Effectively the current "minor" version disappears. 

No, effectively the current "major" number disappears, with the minor
assuming the major role it already had.

-- 
Viktor.

___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Matthias St. Pierre

I like Richard's approach (with the '8' or another number) and  I don't think 
it is
contradicting semantic versioning. Maybe a good compromise between  your two
opposing views would be to make the encoding irrelevant to our users by 
introducing
version check macros like

       OPENSSL_MAKE_VERSION(maj,min,patch)    and
       OPENSSL_VERSION_AT_LEAST(maj,min)

(note: the patch level was omitted from the second macro on purpose)

which enable the application programmer to write code like


    #if OPENSSL_MAKE_VERSION(2.0.0) <= OPENSSL_VERSION_NUMBER
    ...
    #endif


or


    #if OPENSSL_VERSION_AT_LEAST(2,0)
    ...
    #endif


This would work both for programs built for old and new openssl versions.



There was a first failed attempt to introduce such macros, see the threads

https://github.com/openssl/openssl/issues/5961
https://github.com/openssl/openssl/pull/5968


Matthias


___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

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

2018-09-21 Thread Tim Hudson
On Sat, Sep 22, 2018 at 12:32 AM Viktor Dukhovni 
wrote:

> > On Sep 21, 2018, at 10:07 AM, Tim Hudson  wrote:
> >
> > And the output you get:
> >
> > 0x10102000
>
> The trouble is that existing software expects to potential ABI changes
> resulting from changes in the 2nd and 3rd nibbles, and if the major
> version is just in the first nibble, our minor version changes will
> look like major number changes to such software.
>

The problem is that we documented a major.minor.fix.patch as our versioning
scheme and semantic versioning is different.
Semantic versioning does not allow for breaking changes on the minor
version - and that is what we do in OpenSSL currently.
Part of the requests that have come in for semantic versioning is to
actually do what is "expected".

Basically our significant version changes alter the minor version field in
the OPENSSL_VERSION_NUMBER structure.
And we have loosely referred to those as major releases but not changed the
actual major version field - but the minor.

The simple way to look at this: for OpenSSL-1.0.2a:
- what is the major version number - the answer is clearly "1".
- what is the minor version number - the answer is clearly "0"
- what is the fix version number - the answer is clear "2"
- what is the patch version number - the answer is clearly "a"

If you repeat that in semantic versioning concepts just using the labels
for mapping you get:
- what is the major version number - the answer is clearly "1".
- what is the minor version number - the answer is clearly "0"
- what is the fix version number - there is no such thing
- what is the patch version number - the answer is clearly "2" (reusing the
fix version)

If you repeat that in semantic versioning concepts just using the actual
definitions:
- what is the major version number - the answer is clearly "1".
- what is the minor version number - the answer is probably "2"
- what is the fix version number - there is no such thing
- what is the patch version number - the answer is probably "0"

Semantic versioning does not have the concept of a fix version separate
from a patch version - those are just a fix version.
If you add or deprecate APIs you have a new minor version. If you fix bugs
without touching the API is it a patch version.
If you break anything in the API is a major version.
It is completely totally about the API itself.

And for OpenSSL we are API compatible for most releases - except when we
did the major change for 1.1.0 which in reality semantic versioning would
have called 2.0.0

Semantic versioning does not have the concept of an API and a ABI
distinction.
In OpenSSL we have if the major.minor is the same then we are ABI
compatible. That is what doesn't exist in the semantic versioning approach
- it is about the API.

Effectively the current "minor" version disappears.

Tim.
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

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

2018-09-21 Thread Viktor Dukhovni



> On Sep 21, 2018, at 10:07 AM, Tim Hudson  wrote:
> 
> And the output you get:
> 
> 0x10102000

The trouble is that existing software expects to potential ABI changes 
resulting from changes in the 2nd and 3rd nibbles, and if the major
version is just in the first nibble, our minor version changes will
look like major number changes to such software.

One could take the view that software that uses the OpenSSL version number
for more than inequalities is in a state of sin, and should stop doing
that, and perhaps doing that is not typical application behaviour, but
what Richard is trying to do is embed the semantic version number in
a wider field that allows us to keep the pre-release bits (which are
useful), to have an epoch nibble for versioning the version format,
and also keep the "significance" of the existing nibbles with the
2nd/3rd nibble signalling major changes while the 4th/5th are minor
version feature additions and 6th/7th are micro fix versions. the
8th nibble indicates dev/pre with 0xF signalling release.

This does not violate semantic versioning, if I only want to
support the *released* version of version 1.2.3, I'll test for
>= 0x?010203FUL, with "?" the epoch nibble (2 or 3).  If I
am planning to test pre-release features I can compare with
>= 0x?0102030UL.

We might not have done it this way if this were the first
even release of OpenSSL, but I think it is a find proposal.

-- 
-- 
Viktor.

___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread 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 

#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 
wrote:

> In message  w2o_njr8bfoor...@mail.gmail.com> on Fri, 21 Sep 2018 23:01:03 +1000, Tim
> Hudson  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 levi...@openssl.org
> OpenSSL Project http://www.openssl.org/~levitte/
> ___
> openssl-project mailing list
> openssl-project@openssl.org
> https://mta.openssl.org/mailman/listinfo/openssl-project
>
___
openssl-project 

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

2018-09-21 Thread Viktor Dukhovni


> On Sep 21, 2018, at 9:35 AM, Richard Levitte  wrote:
> 
> In that case, we should probably just thrown away
> OPENSSL_VERSION_NUMBER.

Sorry, that must not t happen and there's no need.  My sense is that Tim
may end up "in the rough" on this issue, so unless there's more evidence
of support for his "strict" interpretation, I don't think you need to
consider any radical changes as yet.

Just set the high nibble to 2 for backwards compatibility, and as long as
we stick with semantic versioning, we never change it (at least not until
OpenSSL major number 256).  The "epoch" nibble is then signifies the
version of the versioning  scheme, and as long as we're doing semantic
versioning and the major number is 255 or less, it does not change.

If we wanted to make a concession to coëxistence with LibreSSL (which I
do not), we could go with an initial epoch of "3" rather than 2.

Personally, I think that making it clear that OPENSSL_VERSION_NUMBER
is a name in the OpenSSL and not LibreSSL namespace is a good thing.
LibreSSL should have stayed with "1.0.2" and encoded their version
elsewhere.  Their squatting on "2.x.y" is their fault, and I don't
see any need to make concessions to avoid "conflicts".

Software that wants to be compatible with both, and wants to use the
version number to select implementations of various features, needs
to make LibreSSL-specific choices only when some LibreSSL-specific
macro indicates that it is compiled with LibreSSL.

-- 
-- 
Viktor.

___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

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

2018-09-21 Thread Viktor Dukhovni
I support Richard's numeric scheme as proposed, with one small change.

I think that setting the epoch to 8 to set the high bit is neither
necessary nor wise.  Though the numeric version constant should be
manifestly unsigned (UL suffix not L), and having the top 3 nibbles
for the "effective" major version maximizes compatibility with prior
practice for most users, making the number negative if treated as
signed is not a good idea at this time.

Since we're making a change to semantic versioning, I'd bump the
epoch to 2.  This means that some (not common) software that
reconstructs the version string from the numeric constant (e.g.
Postfix when warning about run-time vs. compile-time mismatch)
gets something vaguely sensible:

0x202FL  -> "2.2.0" (rather than "2.0.0")

I'll have to adjust Postfix to produce better version mismatch
reports (which really should not happen since the SONAME prevents
running with an incompatible shared library, so perhaps remove the
check, but Wietse may be difficult to convince, my problem...)

> On Sep 21, 2018, at 5:58 AM, Richard Levitte  wrote:
> 
> I've worked on a proposal for an update of the OpenSSL version scheme,
> to basically align ourselves with semantic versioning, most of all in
> presentation, but also in spirit, while retaining numeric
> compatibility.  This proposal is currently in the form of a Google
> Document:
> 
> https://docs.google.com/document/d/1H3HSLxHzg7Ca3WQEU-zsOd1lUP_uJieHw5Dae34KPBs/

-- 
Viktor.

___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Richard Levitte
In message  
on Fri, 21 Sep 2018 23:01:03 +1000, Tim Hudson  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 levi...@openssl.org
OpenSSL Project http://www.openssl.org/~levitte/
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Tim Hudson
Now I get the conceptual issue that Richard and Matt are differing on - and
it is about actually replacing OpenSSL's versioning concept with semantic
versioning compared to adopting semantic versioning principles without
actually being precisely a semantic version approach.

The whole concept of semantic versioning is that you define *precisely *what
you mean by a version.
Everywhere you have the concept of a version you must use the semantic form
of a *version encoding*.

That is the X.Y.Z[-prerelease][+buildmeta] format that is documented along
with the rules for X.Y.Z in terms of your public API.
And all other information about a version goes into prerelease and into
buildmeta.
Both prerelease and buildmeta are allowed to be a sequence of dot separated
alphanumerichyphen combinations.

This is the point of semantic versioning. All versions for all products are
all represented with the same sort of concepts and you know what the rules
are for the numeric X.Y.Z handling and the parsing rules for prerelease and
buildmeta.

Our concepts of versioning within OpenSSL if expressed in semantic form
MUST fit into this approach.
No prefixes. No suffixes. Not special additional encoding The idea is
consistency.

When dealing with API issues you only ever need to see X.Y.Z for any code
related testing - it precisely identifies a point in time API release.
There should never be any code ever that varies that requires looking at
prerelease or buildmeta in order to perform any action in terms of the code.

That maps to our concept of OPENSSL_VERSION_NUMBER

For the human reporting we should have the fill concept which is a text
string - and that should be OPENSSL_VERSION_TEXT and that means not having
anything else within the text other than the actual semantic version.
The syntax of the semantic version is fixed.

If you want to keep the concept of a build date in the macro you are
calling the version then it must be encoded in that format - or you move
that concept out of the macro that is the version.

Tim.
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

[openssl-project] Release strategy updates

2018-09-21 Thread Matt Caswell
I am very concerned about stability of our API moving forwards. There
are various discussions about changing the version number to 1.2.0 (or
possibly 2.0.0) - which according to our versioning scheme would allow
breaking changes. Whilst this is true I think we need to be very wary
about "opening the flood gates" for breaking changes.

The move from 1.0.x to 1.1.0 was hard on our users and we should avoid
that again.

With that in mind I have opened the following PR (based largely on
wording suggested by Viktor):

https://github.com/openssl/web/pull/82

At the same time I have taken the opportunity to clean up some
out-of-date stuff in the release strategy.

This is independent of the semantic versioning discussion which may
itself see further changes being made to the release strategy.

Thoughts?

Matt
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Richard Levitte
In message  
on Fri, 21 Sep 2018 21:28:55 +1000, Tim Hudson  said:

> So as a concrete example - taking master and the current OPENSSL_VERSION_TEXT 
> value.
> 
> "OpenSSL 1.1.2-dev xx XXX "
> 
> would become
> 
> "1.1.2-dev+xx.XXX."

No, it would become "1.1.2-dev"

I have no idea why you want to shove the date template into the
version number.

> That is what I understand is the point of semantic versioning. You know how 
> to pull apart the
> version string.
> -dev indicates a pre-release version known as "dev"
> +xx.XXX. indicates build metadata.

I haven't seen "xx XXX " as build metadata, only as a template of
the release date, which is part of how we display the version (with
'openssl version').  I don't see it as part of the version string, nor
have our script that do parse out the version from that string *ever*
done that.  You'd have to argue why we should start making it part of
the version now...

> The underlying release is major 1, minor 1, patch 2.

No.  1.1.1 is a minor (feature) release visavi 1.1.0.  1.1.0 is a
major release visavi 1.0.x.  We've talked about 1.2.0 as the next
major release.  Semantically (!) speaking, that tells me that the
middle number is the major version number, the last number is the
minor version number, and the letters after that represent the patch
version number.
This is how we have acted, and this is how our FAQ describes our
version scheme since April 2012.

> But for semantic versioning where we allow API breakage in our
> current minor version we would have to shift everything left.
> And we would then have "1.2.0-dev+xx.XXX." if the planned new
> release wasn't guaranteed API non-breaking with the previous release
> (1.1.1).

Yes (except the '+xx.XXX.' part, just drop that please).  But I'm
not proposing that we do this change as a part of a minor release, I
propose that we do this on the next major release.  In other words,
this would allow us to continue according to the current scheme for
any 1.1.x if we would choose to release one, but that the next major
release would be called 2.0.0 instead of 1.2.0, that the next minor
(feature) release after that would be called 2.1.0 instead of 1.2.1,
and that the fix releases would be called 2.0.1 instead of 1.2.0a,
2.1.1 instead of 1.2.1a, etc etc etc.

Is this clearer to you?

Cheers,
Richard

-- 
Richard Levitte levi...@openssl.org
OpenSSL Project http://www.openssl.org/~levitte/
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Matt Caswell



On 21/09/18 14:01, Tim Hudson wrote:
> 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.

The text form is fully consistent with semantic versioning. Richard's
proposal for the integer form is also fully consistent with the text
form, albeit encoded in a different way to the way you think it should
be encoded.


> 
> 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.

There we disagree. Richard's integer form *is* a representation of the
semantic form. There is nothing in semantic versioning that requires us
to only consider the numeric parts when encoding it.

> 
> 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.

It *is* consistent IMO. Your proposal is just different - it isn't any
more or less consistent - but it has the disadvantage of breaking stuff.

I don't think we are going to get to agreement on this point.

Matt

___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Matt Caswell



On 21/09/18 13:52, Richard Levitte wrote:
> 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.  
I see no reason for the epoch value to be greater. Equal is sufficient
(i.e. setting it to 1 is fine). 0 would not be fine.

There are two requirements for OPENSSL_VERSION_NUMBER afaict:

1) The encoded number should obey the same precedence rules as semantic
versioning, so that equality and inequality tests between version
numbers work as you might expect.

2) We don't break things when compared to how this version number is
used in practice today


Matt
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Richard Levitte
In message  
on Fri, 21 Sep 2018 21:17:12 +1000, Tim Hudson  said:

> i.e. OPENSSL_VERSION_NUMBER should be X.Y.Z

So you mean we'd lose the integer form entirely?  Hey, I have zero
issue with that!  However, that's going to make life hard for everyone
that wants to be able to build against different OpenSSL versions and
use this macro in pre-processing their source.  I don't think we'll
get many happy faces with such a move (talk about an API break and
making life hard on people).

I hope I misunderstand what you're going for...

(hey, if we want to drop that integer, or make it something different,
maybe we should follow the POSIX example and make that MM
(year+month) of the release?  It's incremental and certainly usable
with pre-processing!    and less hard on our users than dropping
the number altogether)

> and OPENSSL_VERSION_TEXT should be "X.Y.Z [-patch][+buildmeta]" and
> that would be a simple, direct, and expected mapping to OpenSSL for
> semantic versioning.

Semantic versioning says MAJOR.MINOR.PATCH, i.e. Z would be the patch
number.  Why you want to have the patch indicator where semantic
versioning has pre-release information (which is exactly what we do
with the -dev and -prex suffixes), I do not understand.

-- 
Richard Levitte levi...@openssl.org
OpenSSL Project http://www.openssl.org/~levitte/
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project


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

2018-09-21 Thread Tim Hudson
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.

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.

Tim.
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

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

2018-09-21 Thread Richard Levitte
In message  
on Fri, 21 Sep 2018 20:48:34 +1000, Tim Hudson  said:

> On Fri, Sep 21, 2018 at 7:58 PM Richard Levitte  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 0x0020L (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 

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

2018-09-21 Thread Tim Hudson
So as a concrete example - taking master and the current
OPENSSL_VERSION_TEXT value.

"OpenSSL 1.1.2-dev  xx XXX "

would become

"1.1.2-dev+xx.XXX."

That is what I understand is the point of semantic versioning. You know how
to pull apart the version string.
-dev indicates a pre-release version known as "dev"
+xx.XXX. indicates build metadata.
The underlying release is major 1, minor 1, patch 2.

But for semantic versioning where we allow API breakage in our current
minor version we would have to shift everything left.
And we would then have "1.2.0-dev+xx.XXX." if the planned new release
wasn't guaranteed API non-breaking with the previous release (1.1.1).

Tim.
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

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

2018-09-21 Thread Tim Hudson
On Fri, Sep 21, 2018 at 9:02 PM Matt Caswell  wrote:

> I think this is an incorrect interpretation of Richard's proposal. The
> OPENSSL_VERSION_NUMBER value is an *integer* value. It does not and
> cannot ever conform to semantic versioning because, because version
> numbers in that scheme are *strings* in a specific format, where
> characters such as "." and "-" have special meanings.
>

It is the version number. We have it in two forms within OpenSSL from a
code perspective  - we have an integer encoding and a text string.
They are precisely what semantic versioning is about - making sure the
versioning concept is represented in what you are using versioning for.

For OpenSSL, codewise we have two macros and two functions that let us
access the build-time version of the macros:
  OPENSSL_VERSION_NUMBER
  OPENSSL_VERSION_TEXT
  OpenSSL_version_num()
  OpenSSL_version()

We also separately have another form of version number - for shared
libraries:
The macro:
  SHLIB_VERSION_NUMBER

We also encode the version number in release packages too.

What semantic versioning is about is sorting out how we represent the
version.
It should impact both OPENSSL_VERSION_NUMBER and OPENSSL_VERSION_TEXT and
it should be consistent.

For the semantic versioning document the status indicator is handled in the
pre-release indicator.
We could limit that to a numeric number and have it in the
OPENSSL_VERSION_NUMBER but I don't think that has helped and semantic
versioning strictly defines precedence handling.

So I would see the simple mapping from semantic versioning very differently
to Richard's write up - and in fact encoding something rather differently
into the OPENSSL_VERSION_NUMBER to my reading and thinking actually goes
against the principles of semantic versioning.

i.e. OPENSSL_VERSION_NUMBER should be X.Y.Z and OPENSSL_VERSION_TEXT should
be "X.Y.Z[-patch][+buildmeta]" and that would be a simple, direct, and
expected mapping to OpenSSL for semantic versioning.

A merged approach or keeping parts of our (non-semantic) approach while not
fully adopting semantic versioning to me at least would be missing the
point.

Tim.
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

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

2018-09-21 Thread Matt Caswell


On 21/09/18 11:48, Tim Hudson wrote:
> On Fri, Sep 21, 2018 at 7:58 PM Richard Levitte  > 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.
> 
> 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?
> 
> 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.
> 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 think this is an incorrect interpretation of Richard's proposal. The
OPENSSL_VERSION_NUMBER value is an *integer* value. It does not and
cannot ever conform to semantic versioning because, because version
numbers in that scheme are *strings* in a specific format, where
characters such as "." and "-" have special meanings.

The semantic version for openssl would be the value of the
OPENSSL_VERSION_NUMBER_TEXT macro (if PR #7285 gets merged).

If we were to adopt semantic versioning then the OPENSSL_VERSION_NUMBER
macro would be an OpenSSL specific encoding of the semantic version
number, useful for the purpose of comparing different version numbers
such that the precedence rules of semantic versioning still apply.

As an OpenSSL specific encoding, we can choose to encode it in any way
we like. This *includes* having a status value if we so wish (and that
actually fits quite nicely with the semantic versioning concept of
pre-releases)



> 
> 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).
> 
> 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.
> 
> 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.

The S field remains useful for checking precedence, i.e. knowing that
1.1.1-pre1 is an older version that 1.1.1.


Matt



___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

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

2018-09-21 Thread Tim Hudson
On Fri, Sep 21, 2018 at 7:58 PM Richard Levitte  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.

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?

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.
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.

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).

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.

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.

Tim.
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

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

2018-09-21 Thread Richard Levitte
Hi,

I've worked on a proposal for an update of the OpenSSL version scheme,
to basically align ourselves with semantic versioning, most of all in
presentation, but also in spirit, while retaining numeric
compatibility.  This proposal is currently in the form of a Google
Document:

https://docs.google.com/document/d/1H3HSLxHzg7Ca3WQEU-zsOd1lUP_uJieHw5Dae34KPBs/

One notable thing with semantic versioning is that it's much stricter
about the meaning of a major release regarding incompatible API/ABI
changes.  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.

See https://semver.org/ for the full definition and description of
semantic versioning.

Please discuss.

I intend to finalize the document at some point and make it a PDF
stored among the policies on our web (submitted as a PR of course) and
start a vote on its final inclusion.

Cheers,
Richard

-- 
Richard Levitte levi...@openssl.org
OpenSSL Project http://www.openssl.org/~levitte/
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project