Re: [openssl-project] Release strategy updates

[Matt Caswell]

On 14/01/2019 15:21, Matt Caswell wrote:
> 
> 
> On 21/09/2018 14:19, Matt Caswell wrote:
>> 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
>>
> 
> A somewhat tardy follow up on this...I updated this PR with the latest 
> comments
> so please take a look.

Another update to the PR. Most significantly I merged the commits from PR 104
into this one.

Please take another look. In particular I guess the most controversial bit is
the the stability policy words at the end.

Matt

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

Re: [openssl-project] Release strategy updates

[Matt Caswell]

On 21/09/2018 14:19, Matt Caswell wrote:
> 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
> 

A somewhat tardy follow up on this...I updated this PR with the latest comments
so please take a look.

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

Re: [openssl-project] Release strategy updates & other policies

[Matt Caswell]

On 26/09/18 18:24, Viktor Dukhovni wrote:
> 
> 
>> On Sep 25, 2018, at 9:51 AM, Matt Caswell  wrote:
>>
>> 5.0.0
>> 5.0.1 (bug fix)
>> 5.1.0 (add accessor)
>>   6.0.0 (new feature)
>>   6.0.1 (bug fix)
>> 5.1.1 (bug fix)6.0.2 (bug fix)
>> 5.2.1 (add accessor)
>>   6.1.0 (add accessor)
> 
> Previously, we could add non-triviall features in "z+1" of "x.y.z",
> with a stable ABI moving forward from "x.y.z" to "x.y.(z+1)".
> 
> Thus, e.g. 1.1.1 is a feature evolution of 1.1.0.  With this, we seem
> to lose the ability to produce a manifestly (forward) ABI-compatible
> feature release, that's a drop-in replacement for a previous release.

Yes. This is a consequence of going with semver that I don't see any way
of avoiding. At least not without a radical shift in the way we support
releases.

> 
> I would have expected to have 5.1.x as an ABI compatible upgrade of
> 5.0 with non-trivial new features.
> 
> The trivial API updates in stable releases (new accessors for forward
> compatibility, ...) would go into the micro version along with the
> bug fixes.  And should be made for the same reason.
> 
> In the case of new accessors, their visibility should conditioned
> the user defining a suitable macro to make them visible.  Their
> purpose is to facilitate compiling code that's forward-ported
> to a later release, but needs to still work with the stable
> release.  Otherwise, there really should be no feature changes
> in stable releases.

If I'm reading you correctly then you seem to be suggesting that we
avoid the semver rules through some clever slight-of-hand based on
conditional macros, i.e. we add new accessors into PATCH releases, but
we hide them away behind a conditional macro.

It means, effectively, that people cannot rely on the semver versioning
if they happen to be using those macros. This seems to make the whole
exercise utterly pointless in my mind. Either we go with semver and
totally commit to it - or we stick with what we've already got. No
half-way, "well we're kind of doing semver, but not really".


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

Re: [openssl-project] Release strategy updates & other policies

[Richard Levitte]

In message <73e9cd06-575e-4cde-b137-95179b07b...@dukhovni.org> on Wed, 26 Sep 
2018 13:24:11 -0400, Viktor Dukhovni  said:

> 
> 
> > On Sep 25, 2018, at 9:51 AM, Matt Caswell  wrote:
> > 
> > 5.0.0
> > 5.0.1 (bug fix)
> > 5.1.0 (add accessor)
> >   6.0.0 (new feature)
> >   6.0.1 (bug fix)
> > 5.1.1 (bug fix)6.0.2 (bug fix)
> > 5.2.1 (add accessor)
> >   6.1.0 (add accessor)
> 
> Previously, we could add non-triviall features in "z+1" of "x.y.z",
> with a stable ABI moving forward from "x.y.z" to "x.y.(z+1)".
> 
> Thus, e.g. 1.1.1 is a feature evolution of 1.1.0.  With this, we seem
> to lose the ability to produce a manifestly (forward) ABI-compatible
> feature release, that's a drop-in replacement for a previous release.

Your interpretation is incorrect, but that's because you're mixing up
our current practice (which is wrong according to our docs), which is
shited right compared to semantic versioning (and our docs).

We have done none-trivial feature additions in "z+1" BECAUSE WE CALLED
THAT A MINOR FEATURE RELEASE.  In semver terms, we should have done
"y+1" instead.
(incidently, our letter release correspond to "z+1" in semver terms)

BTW, "add non-trivial features" isn't really a useful terminology.
The semver trigger for MINOR version bump is "add new functionality to
the public API", regardless of if it's trivial or not.

> I would have expected to have 5.1.x as an ABI compatible upgrade of
> 5.0 with non-trivial new features.
> 
> The trivial API updates in stable releases (new accessors for forward
> compatibility, ...) would go into the micro version along with the
> bug fixes.  And should be made for the same reason.

This is absolutely wrong in semantic versioning.  Compatible APi
*changes* are allowed in PATCH level releases (what you call micro
versions).  And strictly speaking, this doesn't even necessarily
comply with our current practice, see this FAQ text:

Letter releases (e.g. 1.0.1a) can only contain bug and security
fixes and no new features. Minor releases change the last number
(e.g. 1.0.2) and can contain new features that retain binary
compatibility.

I noticed that you mentioned "drop-in"...  the way we've designed
things so far, our minor releases produce libraries that can replace
the same libraries from earlier minor releases in the same major
series.

> In the case of new accessors, their visibility should conditioned
> the user defining a suitable macro to make them visible.  Their
> purpose is to facilitate compiling code that's forward-ported
> to a later release, but needs to still work with the stable
> release.  Otherwise, there really should be no feature changes
> in stable releases.

This is where opinions seem to diverge.  I have had a change of heart,
new accessors should have trigger a new minor release and not been
added as a letter (micro) release.

What I see happening is, of course, that we will have more frequent
minor releases, and that minor release may work as an upgrade from an
earlier patch release.  The latter will essentially depending on how
we decide to branch going forward (Matt, branching on major releases
starts to make sense, incidently...  I'm not totally convinced yet,
but...)

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] Release strategy updates & other policies

[Viktor Dukhovni]

> On Sep 25, 2018, at 9:51 AM, Matt Caswell  wrote:
> 
> 5.0.0
> 5.0.1 (bug fix)
> 5.1.0 (add accessor)
>   6.0.0 (new feature)
>   6.0.1 (bug fix)
> 5.1.1 (bug fix)6.0.2 (bug fix)
> 5.2.1 (add accessor)
>   6.1.0 (add accessor)

Previously, we could add non-triviall features in "z+1" of "x.y.z",
with a stable ABI moving forward from "x.y.z" to "x.y.(z+1)".

Thus, e.g. 1.1.1 is a feature evolution of 1.1.0.  With this, we seem
to lose the ability to produce a manifestly (forward) ABI-compatible
feature release, that's a drop-in replacement for a previous release.

I would have expected to have 5.1.x as an ABI compatible upgrade of
5.0 with non-trivial new features.

The trivial API updates in stable releases (new accessors for forward
compatibility, ...) would go into the micro version along with the
bug fixes.  And should be made for the same reason.

In the case of new accessors, their visibility should conditioned
the user defining a suitable macro to make them visible.  Their
purpose is to facilitate compiling code that's forward-ported
to a later release, but needs to still work with the stable
release.  Otherwise, there really should be no feature changes
in stable releases.

So, Matt, we're not on the same page just yet...

-- 
-- 
Viktor.

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

Re: [openssl-project] Release strategy updates & other policies

[Richard Levitte]

Speaking of this, I've started on a document that explores the meaning
of changes and releases.  Its objective is to create discussion and
debate, and hopefully, we will eventually be able to create a working
policy with sufficient detail.

https://docs.google.com/document/d/1fCt_tgK9V1pp1aeR80sMmyH1h74cZ_fQg2b76z560UY/

There are some example cases that I could think of, please feel free
to add.  It also discusses ABI changes, and also mentions the CLI.

Cheers,
Richard ( currently brain freeze, can't think of more to write )

-- 
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] Release strategy updates & other policies

[Richard Levitte]

In message <20180926165825.ga14...@roeckx.be> on Wed, 26 Sep 2018 18:58:26 
+0200, Kurt Roeckx  said:

> On Tue, Sep 25, 2018 at 08:13:53PM +1000, Tim Hudson wrote:
> > On Tue, Sep 25, 2018 at 8:07 PM Matt Caswell  wrote:
> > 
> > > On 25/09/18 10:58, Tim Hudson wrote:
> > > > On Tue, Sep 25, 2018 at 7:23 PM Richard Levitte  > > > > wrote:
> > > >
> > > > So what you suggest (and what I'm leaning toward) means that we will
> > > > change our habits.
> > > >
> > > >
> > > > Adoption of semantic versioning will indeed require us to change our
> > > > habits in a number of areas - that is the point of having a single clear
> > > > definition of what our version numbers mean.
> > > >
> > > > I also do think we need to document a few things like what we mean by
> > > > bug fix compared to a feature update as there are items which we could
> > > > argue could either be a PATCH or a MINOR update depending on how we
> > > > describe such things.
> > >
> > > Sometimes we need to add a function in order to fix a bug. How should
> > > this be handled? e.g. there are 60 functions defined in
> > > util/libcrypto.num in the current 1.1.0i release that weren't there in
> > > the original 1.1.0 release.
> > >
> > 
> > 
> > In semantic versioning those are MINOR releases. The API has changed in a
> > backward compatible manner.
> > They cannot be called PATCH releases - those are only for internal changes
> > that fix incorrect behaviour.
> > If you change the API you are either doing a MINOR or a MAJOR release.
> 
> We might need to add this to multiple branches at the same time.
> 
> Assume that we have a 2.0.5 and 2.1.2 version. And in both
> versions we need to add that a new function, what should the
> new versions be? My understanding is that you can't actually do
> it.

If we have both 2.0.5 and 2.1.2 as current releases, then it means
we've branched at MINOR releases, i.e. we have a 2.0.x branch and a
2.1.x branch.  Semver says that when you add new functionality, the
next release MUST get its MINOR version number increased.  Since the
last MINOR release is 2.1.0, it means that we must release 2.2.0, and
start a new branch for 2.2.x.

If we branch on MAJOR releases, then that situation isn't even
possible, you just cannot have 2.0.5 and 2.1.2 at the same time...
unless you sub-branch, an endeavour I was stand very far away from.

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] Release strategy updates & other policies

[Kurt Roeckx]

On Tue, Sep 25, 2018 at 08:13:53PM +1000, Tim Hudson wrote:
> On Tue, Sep 25, 2018 at 8:07 PM Matt Caswell  wrote:
> 
> > On 25/09/18 10:58, Tim Hudson wrote:
> > > On Tue, Sep 25, 2018 at 7:23 PM Richard Levitte  > > > wrote:
> > >
> > > So what you suggest (and what I'm leaning toward) means that we will
> > > change our habits.
> > >
> > >
> > > Adoption of semantic versioning will indeed require us to change our
> > > habits in a number of areas - that is the point of having a single clear
> > > definition of what our version numbers mean.
> > >
> > > I also do think we need to document a few things like what we mean by
> > > bug fix compared to a feature update as there are items which we could
> > > argue could either be a PATCH or a MINOR update depending on how we
> > > describe such things.
> >
> > Sometimes we need to add a function in order to fix a bug. How should
> > this be handled? e.g. there are 60 functions defined in
> > util/libcrypto.num in the current 1.1.0i release that weren't there in
> > the original 1.1.0 release.
> >
> 
> 
> In semantic versioning those are MINOR releases. The API has changed in a
> backward compatible manner.
> They cannot be called PATCH releases - those are only for internal changes
> that fix incorrect behaviour.
> If you change the API you are either doing a MINOR or a MAJOR release.

We might need to add this to multiple branches at the same time.

Assume that we have a 2.0.5 and 2.1.2 version. And in both
versions we need to add that a new function, what should the
new versions be? My understanding is that you can't actually do
it.


Kurt

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

Re: [openssl-project] Release strategy updates & other policies

[Matt Caswell]

On 25/09/18 14:30, Richard Levitte wrote:
> In message  on Tue, 25 Sep 
> 2018 14:15:32 +0100, Matt Caswell  said:
> 
>> On 25/09/18 14:09, Tim Hudson wrote:
>>> It would also mean our LTS releases are MAJOR.MINOR - as the PATCH is
>>> the fixes we will apply - so it isn't part of the LTS designation as such.
>>> e.g. 5.0.x would be the marker - not 5.0.0 - so 5.0 in shorthand form. 
>>
>> This is where we disagree. My proposal is that the LTS designation would
>> be 5 (not 5.0.x or 5.0.0). We would continue to do updates as we have
>> done except we would have to classify our changes on the LTS branch as
>> either API affecting (e.g. new accessor) or just a bug fix. If the
>> former then the new version becomes an update to the MINOR number,
>> otherwise it is an update to the PATCH number.
> 
> I *like* the idea of an LTS designation on the major number only.
> However, the rest leaves me utterly confused.  Here, it seems that you
> would allow a 5.1.0 minor update in the v5 LTS branch, and yet, you
> say this when responding to my posting:
> 
> In message <989c8546-78e5-8bae-29d7-c9abf1bf7...@openssl.org> on Tue, 25 Sep 
> 2018 14:18:17 +0100, Matt Caswell  said:
> 
>> On 25/09/18 13:25, Richard Levitte wrote:
>>> Added accessors is additions to out API, not a change of our existing
>>> API, let's make that clear.  The choice we can make in the scenario is
>>> to either release 5.2.0 or 6.0.0.  In my mind, both are viable, but
>>> for different reasons.
>>
>> Neither seems viable to me. That would mean you have to add all the
>> features from 5.1.0 into an LTS release. That can't happen.
> 
> I think I need an example timeline from you, 'cause I can see clearly
> how you look at it...

The above was in response to my example of the problem that happens if
you have multiple branches associated with a single MAJOR version
number. In my example 5.0.0 was an LTS release, and 5.1.0 was some other
feature release. The problem was that, in that scenario, if you need to
add an accessor to the LTS release, you can't do it because 5.1.0 is
already used for some other feature release. You can't just call it
5.2.0 and that's the new incarnation of the LTS release because that
means adding all the features from 5.1.0 into the LTS release in the
middle of the LTS cycle.

I see all MAJOR versions as stable releases with a one-to-one
correspondence with a branch. A timeline might look like this


5.0.0
5.0.1 (bug fix)
5.1.0 (add accessor)
   6.0.0 (new feature)
   6.0.1 (bug fix)
5.1.1 (bug fix)6.0.2 (bug fix)
5.2.1 (add accessor)
   6.1.0 (add accessor)

And so on.

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

Re: [openssl-project] Release strategy updates & other policies

[Matt Caswell]

On 25/09/18 14:21, Richard Levitte wrote:
> In message  on Tue, 25 Sep 
> 2018 14:11:11 +0100, Matt Caswell  said:
> 
>>
>>
>> On 25/09/18 13:54, Richard Levitte wrote:
>>> In message <896ece72-8923-801e-b97d-5a1b21c9c...@openssl.org> on Tue, 25 
>>> Sep 2018 13:37:45 +0100, Matt Caswell  said:
>>>
> And that is what semantic versioning is about - it is about the API.
> So if you add to the API you change either MINOR or MAJOR.
> In your scenario the moment you need to add an API you are doing a MINOR
> release and if you already have a MINOR release under the MAJOR then you
> need to add a MINOR on top of the latest MINOR that you have.
> You don't get to make API changing releases that expand the API behind
> the existing releases that are out there.

 Exactly. That is why I am proposing that each time we create a branch it
 is associated with a major release ONLY. You can't have two branches
 with the same major release because that means you cannot make MINOR
 changes on the older branch - even ones that we would historically have
 allowed.
>>>
>>> H?  If we have three major branches 5.0.0, 6.0.0 and 7.0.0, I
>>> don't quite see what would stop us, technically.
>>
>> Is this exactly what I'm proposing? There is no problem if each major
>> release is associated with a different branch. The problem comes if
>> there are two branches on the SAME major version.
> 
> It seems I misread you, then.
> 
> The more I think about it, the more I agree with the MAJOR release
> base for our branches, what I still don't quite catch on is your
> thinking around the release on new MINOR releases...  you seem to say
> that they shouldn't be allowed, at least under certain conditions, or
> always, and question is then, what's the actual difference?

Semantic versioning says that a change to your API means the release is
at least MINOR. Or it could be MAJOR.

Up until now we've had a subtly different rule. Adding a new feature
cannot go into a stable release. We *do* however allow some changes to
the API in a stable release, e.g. new accessors, some limited
constifying, error codes etc (see my other email for other examples).
I'll collectively call these things "trivial API changes".

So, the rules would be:

1) Each MAJOR version has a branch associated with it
2) New features only ever get merged to master.
3) When master is eventually released, a new branch is created for it
and it becomes a new MAJOR version.
4) Trivial API changes can go to any branch
5) When creating a new release from a branch, if there have been any
trivial API changes then we update the MINOR version. Otherwise we
update the PATCH version.


Matt




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

Re: [openssl-project] Release strategy updates & other policies

[Richard Levitte]

In message  on Tue, 25 Sep 
2018 14:15:32 +0100, Matt Caswell  said:

> On 25/09/18 14:09, Tim Hudson wrote:
> > It would also mean our LTS releases are MAJOR.MINOR - as the PATCH is
> > the fixes we will apply - so it isn't part of the LTS designation as such.
> > e.g. 5.0.x would be the marker - not 5.0.0 - so 5.0 in shorthand form. 
> 
> This is where we disagree. My proposal is that the LTS designation would
> be 5 (not 5.0.x or 5.0.0). We would continue to do updates as we have
> done except we would have to classify our changes on the LTS branch as
> either API affecting (e.g. new accessor) or just a bug fix. If the
> former then the new version becomes an update to the MINOR number,
> otherwise it is an update to the PATCH number.

I *like* the idea of an LTS designation on the major number only.
However, the rest leaves me utterly confused.  Here, it seems that you
would allow a 5.1.0 minor update in the v5 LTS branch, and yet, you
say this when responding to my posting:

In message <989c8546-78e5-8bae-29d7-c9abf1bf7...@openssl.org> on Tue, 25 Sep 
2018 14:18:17 +0100, Matt Caswell  said:

> On 25/09/18 13:25, Richard Levitte wrote:
> > Added accessors is additions to out API, not a change of our existing
> > API, let's make that clear.  The choice we can make in the scenario is
> > to either release 5.2.0 or 6.0.0.  In my mind, both are viable, but
> > for different reasons.
> 
> Neither seems viable to me. That would mean you have to add all the
> features from 5.1.0 into an LTS release. That can't happen.

I think I need an example timeline from you, 'cause I can see clearly
how you look at it...

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] Release strategy updates & other policies

[Richard Levitte]

In message  on Tue, 25 Sep 
2018 14:11:11 +0100, Matt Caswell  said:

> 
> 
> On 25/09/18 13:54, Richard Levitte wrote:
> > In message <896ece72-8923-801e-b97d-5a1b21c9c...@openssl.org> on Tue, 25 
> > Sep 2018 13:37:45 +0100, Matt Caswell  said:
> > 
> >>> And that is what semantic versioning is about - it is about the API.
> >>> So if you add to the API you change either MINOR or MAJOR.
> >>> In your scenario the moment you need to add an API you are doing a MINOR
> >>> release and if you already have a MINOR release under the MAJOR then you
> >>> need to add a MINOR on top of the latest MINOR that you have.
> >>> You don't get to make API changing releases that expand the API behind
> >>> the existing releases that are out there.
> >>
> >> Exactly. That is why I am proposing that each time we create a branch it
> >> is associated with a major release ONLY. You can't have two branches
> >> with the same major release because that means you cannot make MINOR
> >> changes on the older branch - even ones that we would historically have
> >> allowed.
> > 
> > H?  If we have three major branches 5.0.0, 6.0.0 and 7.0.0, I
> > don't quite see what would stop us, technically.
> 
> Is this exactly what I'm proposing? There is no problem if each major
> release is associated with a different branch. The problem comes if
> there are two branches on the SAME major version.

It seems I misread you, then.

The more I think about it, the more I agree with the MAJOR release
base for our branches, what I still don't quite catch on is your
thinking around the release on new MINOR releases...  you seem to say
that they shouldn't be allowed, at least under certain conditions, or
always, and question is then, what's the actual difference?

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] Release strategy updates & other policies

[Matt Caswell]

On 25/09/18 13:25, Richard Levitte wrote:
> In message  on Tue, 25 Sep 
> 2018 12:22:44 +0100, Matt Caswell  said:
> 
>>
>>
>> On 25/09/18 12:12, Richard Levitte wrote:
>>> In message <98774a3e-d127-dcd9-c835-3b359d69b...@openssl.org> on Tue, 25 
>>> Sep 2018 11:53:48 +0100, Matt Caswell  said:
>>>


 On 25/09/18 11:48, Richard Levitte wrote:
> You are contradicting yourself.  If we only make new branches for
> MAJOR version number changes, then it will be allowed to add new
> functionality in them, because that's allowed with a MINOR version
> number change.

 You misunderstand me. Yes, its allowed that we can under semantic
 versioning rules. I'm saying we shouldn't.
>>>
>>> You're saying that we should only release new functionality (new APIs)
>>> in MAJOR releases?  Mind telling us why?
>>
>> Lets imagine we release version 5.0.0. We create a branch for it and
>> declare a support period. Its an LTS release. This is a *stable*
>> release, so we shouldn't de-stabilise it by adding new features.
> 
> Side note: I would never make a x.0.0 release an LTS.  That's very
> risky business, and considering things like missing accessors and
> stuff, it would be downright stupid.
> 
>> Later we do some work on some new features in master. They are backwards
>> compatible in terms of API so we release it as version 5.1.0. Its got a
>> separate support period to the LTS release.
>>
>> We fix some bugs in 5.0.0, and release the bug fixes as 5.0.1. All fine
>> so far. But then we realise there is a missing accessor in it. Its an
>> LTS release so its going to be around for a long time - we really need
>> to add the accessor. But we *can't* do it!! Technically speaking,
>> according to the rules of semantic versioning, that is a change to our
>> API - so it needs to be released as a MINOR version change. That would
>> make the new version 5.1.0but we already used that number for our
>> backwards compatible feature release!
> 
> Added accessors is additions to out API, not a change of our existing
> API, let's make that clear.  The choice we can make in the scenario is
> to either release 5.2.0 or 6.0.0.  In my mind, both are viable, but
> for different reasons.

Neither seems viable to me. That would mean you have to add all the
features from 5.1.0 into an LTS release. That can't happen.

Matt



> 
> I understand that your idea of having our release branches based on
> the major releases is what's getting you stuck here, 'cause it
> basically forces you do have everything in one timeline (unless we do
> sub-branches, and uhmmm, just no! m'kay?).  So we would
> essentially have a 5.y.z branch where we would have this straight
> timeline (as an example):
> 
> 5.0.0
> 5.0.1
> 5.0.3
> 5.1.0 (this stops the 5.0.z series)
> 5.1.2
> 5.1.3
> 5.2.0 (this stops the 5.1.z series)
> ...
> 
> With this type of branch, your scenario is already impossible, 'cause
> you can't release 5.0.1 after 5.1.0 LTS, you'll be forced to release
> 5.1.1, and if you add accessors after that, you could release 5.2.0,
> but that means buh-bye for the idea of the 5.1.0 LTS, 'cause you can't
> make any more patch releases on it.  So yeah, I agree in this case
> that we'd be forced to go to a new major release rather than 5.2.0.
> 
> What you got here is a mixup between branch policy and semantic
> versioning.  It got lost in translation...
> 
> Our current pattern is actually to make new stable branches on minor
> releases.  In that case, it would be perfectly feasible to release
> 5.0.1 after 5.1.0 LTS was released ('cause one is on the 5.0 branch
> and the other on the 5.1 branch), and even to release 5.2.0 with new
> accessors (forming the 5.2 branch).
> 
> So generally speaking, it should still be possible to create new minor
> releases in a branch based on major release, but with the caveat that
> it works like an update of the previous minor release (including its
> patch releases), AND that any LTS release basically stops that branch
> from getting new API added ever again.
> 
> Cheers,
> Richard
> 
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

Re: [openssl-project] Release strategy updates & other policies

[Matt Caswell]

On 25/09/18 14:09, Tim Hudson wrote:
> On Tue, Sep 25, 2018 at 11:02 PM Matt Caswell  > wrote:
> 
> You're right on this one. I misread the diff.
> 
> 
> Not a problem - you are doing the look-at-what-we-did and how it would
> be impacted - and that is certainly what we should be doing - working
> through what impact this would have had.
> Semantic versioning is a major change in behaviour with a focus on the
> API being directly reflected in the versioning scheme.
> 
> It does mean that a lot of how we have handled things in the past in
> terms of what was okay to go into a patch release changes.
> Patch release become*pure bug fix *with no API changes (of any form)
> releases and that is very different. 
> We have taken a relatively flexible interpretation - and put in a lot
> more than bug fixes into the letter (patch) releases - we have added
> upwards compatible API additions.
> 
> It would also mean our LTS releases are MAJOR.MINOR - as the PATCH is
> the fixes we will apply - so it isn't part of the LTS designation as such.
> e.g. 5.0.x would be the marker - not 5.0.0 - so 5.0 in shorthand form. 

This is where we disagree. My proposal is that the LTS designation would
be 5 (not 5.0.x or 5.0.0). We would continue to do updates as we have
done except we would have to classify our changes on the LTS branch as
either API affecting (e.g. new accessor) or just a bug fix. If the
former then the new version becomes an update to the MINOR number,
otherwise it is an update to the PATCH number.

I think it is an absolute non-starter to disallow all API affecting
changes in an LTS release (or indeed any stable release).

Matt

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

Re: [openssl-project] Release strategy updates & other policies

[Matt Caswell]

On 25/09/18 13:54, Richard Levitte wrote:
> In message <896ece72-8923-801e-b97d-5a1b21c9c...@openssl.org> on Tue, 25 Sep 
> 2018 13:37:45 +0100, Matt Caswell  said:
> 
>>> And that is what semantic versioning is about - it is about the API.
>>> So if you add to the API you change either MINOR or MAJOR.
>>> In your scenario the moment you need to add an API you are doing a MINOR
>>> release and if you already have a MINOR release under the MAJOR then you
>>> need to add a MINOR on top of the latest MINOR that you have.
>>> You don't get to make API changing releases that expand the API behind
>>> the existing releases that are out there.
>>
>> Exactly. That is why I am proposing that each time we create a branch it
>> is associated with a major release ONLY. You can't have two branches
>> with the same major release because that means you cannot make MINOR
>> changes on the older branch - even ones that we would historically have
>> allowed.
> 
> H?  If we have three major branches 5.0.0, 6.0.0 and 7.0.0, I
> don't quite see what would stop us, technically.

Is this exactly what I'm proposing? There is no problem if each major
release is associated with a different branch. The problem comes if
there are two branches on the SAME major version.

Matt

> 
> 5.0.0
> 5.0.1
> 5.1.0
> 5.1.1
>6.0.0(new branch)
>6.0.1
>6.0.2
>   7.0.0 (new branch)
>6.0.3
>6.1.0
> 5.1.2
>   7.0.1
>   7.1.0
> 5.2.0
>6.1.2
>6.2.0
> 
> Nothing in major based branching stops this from happening.  The only
> thing you stop is new patches on the next to last minor release in any
> given branch.
> 
> Cheers,
> Richard
> 
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

Re: [openssl-project] Release strategy updates & other policies

[Tim Hudson]

On Tue, Sep 25, 2018 at 11:02 PM Matt Caswell  wrote:

> You're right on this one. I misread the diff.
>

Not a problem - you are doing the look-at-what-we-did and how it would be
impacted - and that is certainly what we should be doing - working through
what impact this would have had.
Semantic versioning is a major change in behaviour with a focus on the API
being directly reflected in the versioning scheme.

It does mean that a lot of how we have handled things in the past in terms
of what was okay to go into a patch release changes.
Patch release become* pure bug fix *with no API changes (of any form)
releases and that is very different.
We have taken a relatively flexible interpretation - and put in a lot more
than bug fixes into the letter (patch) releases - we have added upwards
compatible API additions.

It would also mean our LTS releases are MAJOR.MINOR - as the PATCH is the
fixes we will apply - so it isn't part of the LTS designation as such.
e.g. 5.0.x would be the marker - not 5.0.0 - so 5.0 in shorthand form.

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

Re: [openssl-project] Release strategy updates & other policies

[Tim Hudson]

On Tue, Sep 25, 2018 at 10:37 PM Matt Caswell  wrote:

> - Added some new macros:
> https://github.com/openssl/openssl/pull/6037


No we didn't change our public API for this one - we changed *internals*.
The change to include/openssl/crypto.h was entirely changing *comments* to
document that the internals used more of a reserved space - but the API
wasn't changed.

And it isn't a matter of what we did for each item - it is a matter of
could we have fixed certainly things that we would classify as *bugs*
without impacting the API - we didn't have that as a rule - but if we did
then what would we have done.
And where we missed an API then it is not a PATCH. Where we got something
that wasn't spelled correctly - it has to wait for a MINOR to be fixed. A
patch doesn't change APIs.

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

Re: [openssl-project] Release strategy updates & other policies

[Richard Levitte]

In message <896ece72-8923-801e-b97d-5a1b21c9c...@openssl.org> on Tue, 25 Sep 
2018 13:37:45 +0100, Matt Caswell  said:

> > And that is what semantic versioning is about - it is about the API.
> > So if you add to the API you change either MINOR or MAJOR.
> > In your scenario the moment you need to add an API you are doing a MINOR
> > release and if you already have a MINOR release under the MAJOR then you
> > need to add a MINOR on top of the latest MINOR that you have.
> > You don't get to make API changing releases that expand the API behind
> > the existing releases that are out there.
> 
> Exactly. That is why I am proposing that each time we create a branch it
> is associated with a major release ONLY. You can't have two branches
> with the same major release because that means you cannot make MINOR
> changes on the older branch - even ones that we would historically have
> allowed.

H?  If we have three major branches 5.0.0, 6.0.0 and 7.0.0, I
don't quite see what would stop us, technically.

5.0.0
5.0.1
5.1.0
5.1.1
   6.0.0(new branch)
   6.0.1
   6.0.2
  7.0.0 (new branch)
   6.0.3
   6.1.0
5.1.2
  7.0.1
  7.1.0
5.2.0
   6.1.2
   6.2.0

Nothing in major based branching stops this from happening.  The only
thing you stop is new patches on the next to last minor release in any
given branch.

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] Release strategy updates & other policies

[Matt Caswell]

On 25/09/18 13:03, Tim Hudson wrote:
> On Tue, Sep 25, 2018 at 9:22 PM Matt Caswell  > wrote:
> 
> Lets imagine we release version 5.0.0. We create a branch for it and
> declare a support period. Its an LTS release. This is a *stable*
> release, so we shouldn't de-stabilise it by adding new features.
> 
> Later we do some work on some new features in master. They are backwards
> compatible in terms of API so we release it as version 5.1.0. Its got a
> separate support period to the LTS release.
> 
> We fix some bugs in 5.0.0, and release the bug fixes as 5.0.1. All fine
> so far. But then we realise there is a missing accessor in it. Its an
> LTS release so its going to be around for a long time - we really need
> to add the accessor. But we *can't* do it!! Technically speaking,
> according to the rules of semantic versioning, that is a change to our
> API - so it needs to be released as a MINOR version change. That would
> make the new version 5.1.0but we already used that number for our
> backwards compatible feature release!
> 
> 
> And that is what semantic versioning is about - it is about the API.
> So if you add to the API you change either MINOR or MAJOR.
> In your scenario the moment you need to add an API you are doing a MINOR
> release and if you already have a MINOR release under the MAJOR then you
> need to add a MINOR on top of the latest MINOR that you have.
> You don't get to make API changing releases that expand the API behind
> the existing releases that are out there.

Exactly. That is why I am proposing that each time we create a branch it
is associated with a major release ONLY. You can't have two branches
with the same major release because that means you cannot make MINOR
changes on the older branch - even ones that we would historically have
allowed.

> 
> That is not how a semantically versioned project behaves.
> 
> The rules are strict for a reason to stop some of the practices that we
> have - where PATCH releases add APIs. 
> 
> Part of the precondition for a semantically versioned project is that
> the API (and in this sense this is the public API) is under "control" as
> such. 
> 
> I think there are very few circumstances under which we have needed to
> add APIs - and I think outside of accessor functions during the opacity

Looking through changes we have made to 1.1.0 headers there are more
than just accessor functions:

- Add "const" qualifiers to functions
- Add error function or reason codes
- Not sure what to classify this change
as:https://github.com/openssl/openssl/pull/6874
- This change modified some public macro values in 1.1.0:
https://github.com/openssl/openssl/pull/6075/files
- This change modified the way declaration warnings are handled in 1.1.0
public headers:
 https://github.com/openssl/openssl/pull/6688
- We deprecated a function which was documented as deprecated, should
have been deprecated, but wasn't inside the deprecated guards:
https://github.com/openssl/openssl/pull/6588
- We added a whole set of functions for creating X509_LOOKUP_METHODS:
https://github.com/openssl/openssl/pull/6152
- Added some new macros:
https://github.com/openssl/openssl/pull/6037
- We removed a macro added in a previous "letter" release because we
realised it was a mistake:
https://github.com/openssl/openssl/pull/5968
- Fixed a typo in a macro name:
 https://github.com/openssl/openssl/pull/3292
- Added a new SSL_OP_NO_ code
https://github.com/openssl/openssl/pull/4901

There's a stack load more changes than this. I stopped looking after a
relatively short time. Probably (almost) all of these would have to be
released as a new MINOR version number under semantic versioning. I
don't see this changing as we move into the future.

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

Re: [openssl-project] Release strategy updates & other policies

[Richard Levitte]

In message  on Tue, 25 Sep 
2018 12:22:44 +0100, Matt Caswell  said:

> 
> 
> On 25/09/18 12:12, Richard Levitte wrote:
> > In message <98774a3e-d127-dcd9-c835-3b359d69b...@openssl.org> on Tue, 25 
> > Sep 2018 11:53:48 +0100, Matt Caswell  said:
> > 
> >>
> >>
> >> On 25/09/18 11:48, Richard Levitte wrote:
> >>> You are contradicting yourself.  If we only make new branches for
> >>> MAJOR version number changes, then it will be allowed to add new
> >>> functionality in them, because that's allowed with a MINOR version
> >>> number change.
> >>
> >> You misunderstand me. Yes, its allowed that we can under semantic
> >> versioning rules. I'm saying we shouldn't.
> > 
> > You're saying that we should only release new functionality (new APIs)
> > in MAJOR releases?  Mind telling us why?
> 
> Lets imagine we release version 5.0.0. We create a branch for it and
> declare a support period. Its an LTS release. This is a *stable*
> release, so we shouldn't de-stabilise it by adding new features.

Side note: I would never make a x.0.0 release an LTS.  That's very
risky business, and considering things like missing accessors and
stuff, it would be downright stupid.

> Later we do some work on some new features in master. They are backwards
> compatible in terms of API so we release it as version 5.1.0. Its got a
> separate support period to the LTS release.
> 
> We fix some bugs in 5.0.0, and release the bug fixes as 5.0.1. All fine
> so far. But then we realise there is a missing accessor in it. Its an
> LTS release so its going to be around for a long time - we really need
> to add the accessor. But we *can't* do it!! Technically speaking,
> according to the rules of semantic versioning, that is a change to our
> API - so it needs to be released as a MINOR version change. That would
> make the new version 5.1.0but we already used that number for our
> backwards compatible feature release!

Added accessors is additions to out API, not a change of our existing
API, let's make that clear.  The choice we can make in the scenario is
to either release 5.2.0 or 6.0.0.  In my mind, both are viable, but
for different reasons.

I understand that your idea of having our release branches based on
the major releases is what's getting you stuck here, 'cause it
basically forces you do have everything in one timeline (unless we do
sub-branches, and uhmmm, just no! m'kay?).  So we would
essentially have a 5.y.z branch where we would have this straight
timeline (as an example):

5.0.0
5.0.1
5.0.3
5.1.0   (this stops the 5.0.z series)
5.1.2
5.1.3
5.2.0   (this stops the 5.1.z series)
...

With this type of branch, your scenario is already impossible, 'cause
you can't release 5.0.1 after 5.1.0 LTS, you'll be forced to release
5.1.1, and if you add accessors after that, you could release 5.2.0,
but that means buh-bye for the idea of the 5.1.0 LTS, 'cause you can't
make any more patch releases on it.  So yeah, I agree in this case
that we'd be forced to go to a new major release rather than 5.2.0.

What you got here is a mixup between branch policy and semantic
versioning.  It got lost in translation...

Our current pattern is actually to make new stable branches on minor
releases.  In that case, it would be perfectly feasible to release
5.0.1 after 5.1.0 LTS was released ('cause one is on the 5.0 branch
and the other on the 5.1 branch), and even to release 5.2.0 with new
accessors (forming the 5.2 branch).

So generally speaking, it should still be possible to create new minor
releases in a branch based on major release, but with the caveat that
it works like an update of the previous minor release (including its
patch releases), AND that any LTS release basically stops that branch
from getting new API added ever again.

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] Release strategy updates & other policies

[Tim Hudson]

On Tue, Sep 25, 2018 at 9:22 PM Matt Caswell  wrote:

> Lets imagine we release version 5.0.0. We create a branch for it and
> declare a support period. Its an LTS release. This is a *stable*
> release, so we shouldn't de-stabilise it by adding new features.
>
> Later we do some work on some new features in master. They are backwards
> compatible in terms of API so we release it as version 5.1.0. Its got a
> separate support period to the LTS release.
>
> We fix some bugs in 5.0.0, and release the bug fixes as 5.0.1. All fine
> so far. But then we realise there is a missing accessor in it. Its an
> LTS release so its going to be around for a long time - we really need
> to add the accessor. But we *can't* do it!! Technically speaking,
> according to the rules of semantic versioning, that is a change to our
> API - so it needs to be released as a MINOR version change. That would
> make the new version 5.1.0but we already used that number for our
> backwards compatible feature release!
>

And that is what semantic versioning is about - it is about the API.
So if you add to the API you change either MINOR or MAJOR.
In your scenario the moment you need to add an API you are doing a MINOR
release and if you already have a MINOR release under the MAJOR then you
need to add a MINOR on top of the latest MINOR that you have.
You don't get to make API changing releases that expand the API behind the
existing releases that are out there.

That is not how a semantically versioned project behaves.

The rules are strict for a reason to stop some of the practices that we
have - where PATCH releases add APIs.

Part of the precondition for a semantically versioned project is that the
API (and in this sense this is the public API) is under "control" as such.

I think there are very few circumstances under which we have needed to add
APIs - and I think outside of accessor functions during the opacity changes
- I don't know that there were any API additions that weren't actually
avoidable by solving the problem without adding an API. I don't know - I
haven't checked - but none leap to the front on mind. We have done that
simply because we didn't have a strict rule in place about API additions -
we do about changes or deletions - but we tend to view additions as
relatively safe (and they are from a backwards compatible perspective - but
they are not from a semantic versioning point of view).

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

Re: [openssl-project] Release strategy updates & other policies

[Matt Caswell]

On 25/09/18 12:12, Richard Levitte wrote:
> In message <98774a3e-d127-dcd9-c835-3b359d69b...@openssl.org> on Tue, 25 Sep 
> 2018 11:53:48 +0100, Matt Caswell  said:
> 
>>
>>
>> On 25/09/18 11:48, Richard Levitte wrote:
>>> In message  on Tue, 25 
>>> Sep 2018 11:30:39 +0100, Matt Caswell  said:
>>>


 On 25/09/18 11:13, Tim Hudson wrote:
> On Tue, Sep 25, 2018 at 8:07 PM Matt Caswell  > wrote:
>
> On 25/09/18 10:58, Tim Hudson wrote:
> > On Tue, Sep 25, 2018 at 7:23 PM Richard Levitte
> mailto:levi...@openssl.org>
> > >> wrote:
> >
> >     So what you suggest (and what I'm leaning toward) means that
> we will
> >     change our habits.
> >
> >
> > Adoption of semantic versioning will indeed require us to change our
> > habits in a number of areas - that is the point of having a single
> clear
> > definition of what our version numbers mean.
> >
> > I also do think we need to document a few things like what we mean 
> by
> > bug fix compared to a feature update as there are items which we 
> could
> > argue could either be a PATCH or a MINOR update depending on how we
> > describe such things.
>
> Sometimes we need to add a function in order to fix a bug. How should
> this be handled? e.g. there are 60 functions defined in
> util/libcrypto.num in the current 1.1.0i release that weren't there in
> the original 1.1.0 release.
>
>
>
> In semantic versioning those are MINOR releases. The API has changed in
> a backward compatible manner.
> They cannot be called PATCH releases - those are only for internal
> changes that fix incorrect behaviour.
> If you change the API you are either doing a MINOR or a MAJOR release.
>
> Now I think the flexibility we added during 1.1.0 when the MAJOR change
> was to make APIs opaque was a different context where our API remained
> unstable (in semantic terms) yet we did a release (for other reasons).
> Under semantic versioning, 1.1.0 would have been called 2.0.0 and we
> would have had to batch up the accessor API additions into a 2.1.0
> release and not have those included in any 2.0.X PATCH release.
>
> It is quite a change under semantic versioning in some areas as it
> basically requires the version to reflect API guarantees. 

 I don't think we should batch up accessor API additions. Or in fact any
 others. We should release them at the right time as we do now. A move to
 semantic versioning shouldn't change that. That has implications for the
 way we manage branches and support periods/LTS.
>>>
>>> Most of all, it may mean more frequent MINOR releases.
>>>
 I suggest that we only create new branches for a MAJOR version number
 change. We define the support periods/LTS status relative to the major
 version number. For a given supported major version we may update the
 MINOR or PATCH number at any time dependent on whether we've added any
 new functions or not. What we now think of as a "letter" release could
 be either a MINOR or a PATCH release under semantic versioning
 (dependent on what we've changed/added). We continue with the same
 policy of not adding new features to a stable branch (except where
 necessary to fix a bug).
>>>
>>> You are contradicting yourself.  If we only make new branches for
>>> MAJOR version number changes, then it will be allowed to add new
>>> functionality in them, because that's allowed with a MINOR version
>>> number change.
>>
>> You misunderstand me. Yes, its allowed that we can under semantic
>> versioning rules. I'm saying we shouldn't.
> 
> You're saying that we should only release new functionality (new APIs)
> in MAJOR releases?  Mind telling us why?

Lets imagine we release version 5.0.0. We create a branch for it and
declare a support period. Its an LTS release. This is a *stable*
release, so we shouldn't de-stabilise it by adding new features.

Later we do some work on some new features in master. They are backwards
compatible in terms of API so we release it as version 5.1.0. Its got a
separate support period to the LTS release.

We fix some bugs in 5.0.0, and release the bug fixes as 5.0.1. All fine
so far. But then we realise there is a missing accessor in it. Its an
LTS release so its going to be around for a long time - we really need
to add the accessor. But we *can't* do it!! Technically speaking,
according to the rules of semantic versioning, that is a change to our
API - so it needs to be released as a MINOR version change. That would
make the new version 5.1.0but we already used that number for our
backwards compatible feature release!

Matt



> 
>>> I understand the wish to reduce the 

Re: [openssl-project] Release strategy updates & other policies

[Matt Caswell]

On 25/09/18 11:48, Richard Levitte wrote:
> In message  on Tue, 25 Sep 
> 2018 11:30:39 +0100, Matt Caswell  said:
> 
>>
>>
>> On 25/09/18 11:13, Tim Hudson wrote:
>>> On Tue, Sep 25, 2018 at 8:07 PM Matt Caswell >> > wrote:
>>>
>>> On 25/09/18 10:58, Tim Hudson wrote:
>>> > On Tue, Sep 25, 2018 at 7:23 PM Richard Levitte
>>> mailto:levi...@openssl.org>
>>> > >> wrote:
>>> >
>>> >     So what you suggest (and what I'm leaning toward) means that
>>> we will
>>> >     change our habits.
>>> >
>>> >
>>> > Adoption of semantic versioning will indeed require us to change our
>>> > habits in a number of areas - that is the point of having a single
>>> clear
>>> > definition of what our version numbers mean.
>>> >
>>> > I also do think we need to document a few things like what we mean by
>>> > bug fix compared to a feature update as there are items which we could
>>> > argue could either be a PATCH or a MINOR update depending on how we
>>> > describe such things.
>>>
>>> Sometimes we need to add a function in order to fix a bug. How should
>>> this be handled? e.g. there are 60 functions defined in
>>> util/libcrypto.num in the current 1.1.0i release that weren't there in
>>> the original 1.1.0 release.
>>>
>>>
>>>
>>> In semantic versioning those are MINOR releases. The API has changed in
>>> a backward compatible manner.
>>> They cannot be called PATCH releases - those are only for internal
>>> changes that fix incorrect behaviour.
>>> If you change the API you are either doing a MINOR or a MAJOR release.
>>>
>>> Now I think the flexibility we added during 1.1.0 when the MAJOR change
>>> was to make APIs opaque was a different context where our API remained
>>> unstable (in semantic terms) yet we did a release (for other reasons).
>>> Under semantic versioning, 1.1.0 would have been called 2.0.0 and we
>>> would have had to batch up the accessor API additions into a 2.1.0
>>> release and not have those included in any 2.0.X PATCH release.
>>>
>>> It is quite a change under semantic versioning in some areas as it
>>> basically requires the version to reflect API guarantees. 
>>
>> I don't think we should batch up accessor API additions. Or in fact any
>> others. We should release them at the right time as we do now. A move to
>> semantic versioning shouldn't change that. That has implications for the
>> way we manage branches and support periods/LTS.
> 
> Most of all, it may mean more frequent MINOR releases.
> 
>> I suggest that we only create new branches for a MAJOR version number
>> change. We define the support periods/LTS status relative to the major
>> version number. For a given supported major version we may update the
>> MINOR or PATCH number at any time dependent on whether we've added any
>> new functions or not. What we now think of as a "letter" release could
>> be either a MINOR or a PATCH release under semantic versioning
>> (dependent on what we've changed/added). We continue with the same
>> policy of not adding new features to a stable branch (except where
>> necessary to fix a bug).
> 
> You are contradicting yourself.  If we only make new branches for
> MAJOR version number changes, then it will be allowed to add new
> functionality in them, because that's allowed with a MINOR version
> number change.

You misunderstand me. Yes, its allowed that we can under semantic
versioning rules. I'm saying we shouldn't.

> 
> I understand the wish to reduce the number of branches to maintain, we
> must just make sure we know what we're talking about.
> 
> If we would start branching MAJOR releases only, then we'll need some
> kind of policy on what branches are still being developed (i.e new
> MINOR releases are allowed in that branch) and what branches are in
> maintenance mode only (i.e. only new PATCH releases allowed).

All branches are in maintenance mode except master. Typically we only do
PATCH releases for a branch. If we've needed to add a function to a
branch (e.g. a missing accessor) then we make it a MINOR release.
Otherwise we don't add new functionality (as now).

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

Re: [openssl-project] Release strategy updates & other policies

[Richard Levitte]

In message  on Tue, 25 Sep 
2018 11:30:39 +0100, Matt Caswell  said:

> 
> 
> On 25/09/18 11:13, Tim Hudson wrote:
> > On Tue, Sep 25, 2018 at 8:07 PM Matt Caswell  > > wrote:
> > 
> > On 25/09/18 10:58, Tim Hudson wrote:
> > > On Tue, Sep 25, 2018 at 7:23 PM Richard Levitte
> > mailto:levi...@openssl.org>
> > > >> wrote:
> > >
> > >     So what you suggest (and what I'm leaning toward) means that
> > we will
> > >     change our habits.
> > >
> > >
> > > Adoption of semantic versioning will indeed require us to change our
> > > habits in a number of areas - that is the point of having a single
> > clear
> > > definition of what our version numbers mean.
> > >
> > > I also do think we need to document a few things like what we mean by
> > > bug fix compared to a feature update as there are items which we could
> > > argue could either be a PATCH or a MINOR update depending on how we
> > > describe such things.
> > 
> > Sometimes we need to add a function in order to fix a bug. How should
> > this be handled? e.g. there are 60 functions defined in
> > util/libcrypto.num in the current 1.1.0i release that weren't there in
> > the original 1.1.0 release.
> > 
> > 
> > 
> > In semantic versioning those are MINOR releases. The API has changed in
> > a backward compatible manner.
> > They cannot be called PATCH releases - those are only for internal
> > changes that fix incorrect behaviour.
> > If you change the API you are either doing a MINOR or a MAJOR release.
> > 
> > Now I think the flexibility we added during 1.1.0 when the MAJOR change
> > was to make APIs opaque was a different context where our API remained
> > unstable (in semantic terms) yet we did a release (for other reasons).
> > Under semantic versioning, 1.1.0 would have been called 2.0.0 and we
> > would have had to batch up the accessor API additions into a 2.1.0
> > release and not have those included in any 2.0.X PATCH release.
> > 
> > It is quite a change under semantic versioning in some areas as it
> > basically requires the version to reflect API guarantees. 
> 
> I don't think we should batch up accessor API additions. Or in fact any
> others. We should release them at the right time as we do now. A move to
> semantic versioning shouldn't change that. That has implications for the
> way we manage branches and support periods/LTS.

Most of all, it may mean more frequent MINOR releases.

> I suggest that we only create new branches for a MAJOR version number
> change. We define the support periods/LTS status relative to the major
> version number. For a given supported major version we may update the
> MINOR or PATCH number at any time dependent on whether we've added any
> new functions or not. What we now think of as a "letter" release could
> be either a MINOR or a PATCH release under semantic versioning
> (dependent on what we've changed/added). We continue with the same
> policy of not adding new features to a stable branch (except where
> necessary to fix a bug).

You are contradicting yourself.  If we only make new branches for
MAJOR version number changes, then it will be allowed to add new
functionality in them, because that's allowed with a MINOR version
number change.

I understand the wish to reduce the number of branches to maintain, we
must just make sure we know what we're talking about.

If we would start branching MAJOR releases only, then we'll need some
kind of policy on what branches are still being developed (i.e new
MINOR releases are allowed in that branch) and what branches are in
maintenance mode only (i.e. only new PATCH releases allowed).

On the other hand, that would simplify our view of 'master', that will
always be the development of the next major release, which I would say
is a good thing, that will reduce the number of PRs just hanging on
github, waiting for us to decide that we switch master to "next major
release development".

So a generic idea could be that:

- master is always the development of next MAJOR release
- the last current MAJOR release branch can have new functionality
  added, i.e. can have new MINOR releases.
- the second, third etc MAJOR release branch is maintenance only.

>From a version number perspective, this will lead to much more rapid
development (good thing in my mind), and a reduction of MINOR release
branches to maintain (hooray!!!).

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] Release strategy updates & other policies

[Tim Hudson]

On Tue, Sep 25, 2018 at 8:07 PM Matt Caswell  wrote:

> On 25/09/18 10:58, Tim Hudson wrote:
> > On Tue, Sep 25, 2018 at 7:23 PM Richard Levitte  > > wrote:
> >
> > So what you suggest (and what I'm leaning toward) means that we will
> > change our habits.
> >
> >
> > Adoption of semantic versioning will indeed require us to change our
> > habits in a number of areas - that is the point of having a single clear
> > definition of what our version numbers mean.
> >
> > I also do think we need to document a few things like what we mean by
> > bug fix compared to a feature update as there are items which we could
> > argue could either be a PATCH or a MINOR update depending on how we
> > describe such things.
>
> Sometimes we need to add a function in order to fix a bug. How should
> this be handled? e.g. there are 60 functions defined in
> util/libcrypto.num in the current 1.1.0i release that weren't there in
> the original 1.1.0 release.
>


In semantic versioning those are MINOR releases. The API has changed in a
backward compatible manner.
They cannot be called PATCH releases - those are only for internal changes
that fix incorrect behaviour.
If you change the API you are either doing a MINOR or a MAJOR release.

Now I think the flexibility we added during 1.1.0 when the MAJOR change was
to make APIs opaque was a different context where our API remained unstable
(in semantic terms) yet we did a release (for other reasons).
Under semantic versioning, 1.1.0 would have been called 2.0.0 and we would
have had to batch up the accessor API additions into a 2.1.0 release and
not have those included in any 2.0.X PATCH release.

It is quite a change under semantic versioning in some areas as it
basically requires the version to reflect API guarantees.

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

Re: [openssl-project] Release strategy updates & other policies

[Matt Caswell]

On 25/09/18 10:58, Tim Hudson wrote:
> On Tue, Sep 25, 2018 at 7:23 PM Richard Levitte  > wrote:
> 
> So what you suggest (and what I'm leaning toward) means that we will
> change our habits.
> 
> 
> Adoption of semantic versioning will indeed require us to change our
> habits in a number of areas - that is the point of having a single clear
> definition of what our version numbers mean.
> 
> I also do think we need to document a few things like what we mean by
> bug fix compared to a feature update as there are items which we could
> argue could either be a PATCH or a MINOR update depending on how we
> describe such things.

Sometimes we need to add a function in order to fix a bug. How should
this be handled? e.g. there are 60 functions defined in
util/libcrypto.num in the current 1.1.0i release that weren't there in
the original 1.1.0 release.

Matt


> Getting those things documented so we can be consistent is a good thing
> IMHO. The specifics of which we place in PATCH and which we place in
> MINOR are less important than being consistent in handling the same item.
> 
> For example:
> - adding an ASM implementation for performance reasons - is that PATCH
> or MINOR
> - changing an ASM implementation for performance release - is that PATCH
> or MINOR
> - adding an ASM implementation to get constant time behaviour - is that
> PATCH or MINOR
> - changing an ASM implementation for constant time behaviour - is that
> PATCH or MINOR
> 
> For all four of the above examples the API is the same (assuming that
> the low-level APIs are not actually exposed in the public interface for
> any of these).
> And deciding on those depends how you view performance - is it a bug
> that something runs slower than it could - or is it a feature.
> 
> Good arguments can be made for always MINOR or for PATCH - but I think
> we should have a clear view on how we will handle such things going
> forward given the OMC members have differing views on the topic and we
> shouldn't end up with different handling depending on which members in
> which timezone are awake for a given pull request :-)
> 
> Tim.
> 
> 
> 
> 
> ___
> openssl-project mailing list
> openssl-project@openssl.org
> https://mta.openssl.org/mailman/listinfo/openssl-project
> 
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project

Re: [openssl-project] Release strategy updates & other policies

[Richard Levitte]

In message  
on Tue, 25 Sep 2018 18:39:43 +1000, Tim Hudson  said:

> A fairly common approach that is used is that you can only remove something 
> that has been
> marked for deprecation at a MAJOR release version boundary.
> 
> That is entirely independent of the semantic versioning view of things - 
> which also happens to say
> the same thing (that adding a deprecation indication is at least a MINOR 
> release and the removal
> is at a MAJOR release).

Yes, hence the subject change (good call on Paul)

> PATCH versions should never change an API.

Yes.

> So we start warning whenever it is that we decide to deprecate in a MINOR 
> release, but any actual
> removal (actual non-backwards compatible API change) doesn't come in place 
> until a MAJOR
> release.

Well, *so far* we have done deprecation at MAJOR release boundary
only, at east post 1.0.0.  The diverse DEPRECATEDIN_ macros show that.

So what you suggest (and what I'm leaning toward) means that we will
change our habits.

> I see marking things for deprecation is a warning of a pending 
> non-backwards-compatible API
> change - i.e. that there is another way to handle the functionality which is 
> preferred which you
> should have switched across to - but for now we are warning you as the final 
> step before removing
> an API at the next MAJOR release. We haven't committed we will actually 
> remove it - but we have
> warned you that we expect to remove it.

Yes.

-- 
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] Release strategy updates & other policies

[Tim Hudson]

A fairly common approach that is used is that you can only remove something
that has been marked for deprecation at a MAJOR release version boundary.

That is entirely independent of the semantic versioning view of things -
which also happens to say the same thing (that adding a deprecation
indication is at least a MINOR release and the removal is at a MAJOR
release).
PATCH versions should never change an API.
So we start warning whenever it is that we decide to deprecate in a MINOR
release, but any actual removal (actual non-backwards compatible API
change) doesn't come in place until a MAJOR release.

I see marking things for deprecation is a warning of a pending
non-backwards-compatible API change - i.e. that there is another way to
handle the functionality which is preferred which you should have switched
across to - but for now we are warning you as the final step before
removing an API at the next MAJOR release. We haven't committed we will
actually remove it - but we have warned you that we *expect* to remove it.

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

Re: [openssl-project] Release strategy updates & other policies

[Richard Levitte]

In message <20180924.13.2155153469056385673.levi...@openssl.org> on Mon, 24 
Sep 2018 10:00:03 +0200 (CEST), Richard Levitte  said:

> In message <79590c7b-98a4-4816-9eea-52f21b5e23e1@default> on Sun, 23 Sep 2018 
> 20:37:46 -0700 (PDT), Paul Dale  said:
> 
...
> > Some thoughts about this:
> > Should we deprecate functions at a major release or with LTS
> > releases?
> 
> I'm not sure I'd tie that to LTS releases specifically.  Our current
> practice (as seen in the name of our deprecation macros) is to
> deprecate stuff (not just functions...  there are certain openssl app
> commands that I'd like to get rid of) at major release boundary.
> 
> (Incidently, semantic versioning FAQ suggests that deprecation can as
> well happen in a minor release, possibly even preceding a major
> release)
> 
> Also, we must consider if we see deprecation as an incompatible API
> change.  If we do, deprecation can most certainly only happen at major
> release boundary.  My 0.02 SEK is that we should, if we consider the
> configuration option 'no-deprecated' and how deprecation at minor
> release boundary could lead to surprise breakage.

I've been thinking a bit more on this part, and am wavering...  with
our slow pace (it's usually a couple of years between MINOR releases),
deprecating only at MAJOR release boundaries may be quite a stretch to
predict what should go and what shouldn't.  After all, deprecation is
only tacking on a warning that something is going to disappear in a
predictable future, if at all possible to do.

We may have to regard 'no-deprecated' as a development configuration
option only, basically classifying it as "all bets are off".

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] Release strategy updates & other policies

[Richard Levitte]

In message <79590c7b-98a4-4816-9eea-52f21b5e23e1@default> on Sun, 23 Sep 2018 
20:37:46 -0700 (PDT), Paul Dale  said:

> While reading through the lively versioning discussions, it appears
> that there are some fundamentals that seem to lack surrounding
> policies and guidance.

True, we do need some.  At the same time, let's be careful not to get
too regulated...  but we're not quite there, so I'm not worried yet.

> The referenced PR https://github.com/openssl/web/pull/82 starts by
> asking what is our public API?  I'm in the "what's in the header
> files" bucket, which appears to be the consensus.  That's over 5000
> functions and some number of macros.  Is this too many to support
> long term?  I suspect it might be.  The discussion also highlights
> the amount of missing documentation, which is also a concern but not
> the topic here.

It also depends on what the functions are.  Quite a few of them are
very simple getters and setters, or converters (d2i_ and i2d_
functions, which are documented all in one go), i.e. convenience names
that keep the more difficult to use generic functions at bay.

It's quite possible that we can find more user friendly ways to
generalise a lot of them...

> If we have too many APIs, what can we do about it?
> The low level APIs account for about 10% of the total and the FIPS
> project should help clean up some of these.
> 
> That still leaves a lot.  Deprecation seems like a beginning,
> however I've not seen a policy that specifies what or how this is
> done.  Is there one?  If not, it seems prudent to try to create
> one.

There isn't really one written out, as far as I recall.  There is some
kind of concensus among some (I have stayed out of it so far, but am
obviously getting interested...)

> Some thoughts about this:
> Should we deprecate functions at a major release or with LTS
> releases?

I'm not sure I'd tie that to LTS releases specifically.  Our current
practice (as seen in the name of our deprecation macros) is to
deprecate stuff (not just functions...  there are certain openssl app
commands that I'd like to get rid of) at major release boundary.

(Incidently, semantic versioning FAQ suggests that deprecation can as
well happen in a minor release, possibly even preceding a major
release)

Also, we must consider if we see deprecation as an incompatible API
change.  If we do, deprecation can most certainly only happen at major
release boundary.  My 0.02 SEK is that we should, if we consider the
configuration option 'no-deprecated' and how deprecation at minor
release boundary could lead to surprise breakage.

> I'll just use the generic "release" in absence to an answer to this.
> Is it sensible to deprecate functions in one release and remove them
> in the next?  Deprecate and remove two releases later?

Removal is definitely something we only at major release boundary, and
if we continue to do deprecation at major release boundary as well, it
means that deprecation and removal are at least a major release away
from each other.  So the question is what we think we need, or what
the users need.  The current concensus, last I heard it, is that
everything deprecated at 1.1.0 or older will be removed in the next
major release.  Should we reconsider this?

> Would it make more sense to deprecate functions in one release, move
> them to a legacy library in the next and remove them in the third?
> Or even deprecate in the first, move to legacy in the second and let
> them languish there thereafter?

I'm thinking that as long as we can get the users to think that to
reach anything "old" or deprecated, they must link with a legacy
library as well, then I think it should happen immediately, i.e. when
deprecation starts (incidently, advance deprecation, like we've done
with some stuff, will present some build challenges, at least if we
want things maximally automated).

Frankly, though, I don't think we absolutely need to move deprecated
stuff at all.  Something to consider is that there might be stuff that
we want to remove from public API, but still want to use internally...

> Does it make sense to announce APIs that will be deprecated one
> release cycle ahead of doing so?

Uhmmm, not sure I understand.  Isn't deprecation itself an
announcement?  So announcing it in advance, wouldn't that be something
like announcing that we're going to have an announcement soon?

> Macro deprecation might need to be slightly different.

Why?

> Do we have a policy for API changes?  Have we defined what an API
> change is?

No, and not exactly.  The FAQ entry on our current versioning scheme
has an answer, though, says this:

Changes to the middle number are considered major releases and
neither source nor binary compatibility is guaranteed.

I think that's the closest to a written out definition that we have,
and it gives the message that for major releases, any change is fine
on principle, while for minor releases, only compatible source changes
are allowed (for example, 

[openssl-project] Release strategy updates

[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