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

[Matt Caswell]

On 25/09/18 13:56, Tim Hudson wrote:
> 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.

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

> 
> 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
> 
___
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 numbe

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

[Richard Levitte]

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?

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

"as now" is false, we *do* release new functionality in minor
releases.  1.1.1 was a minor release, even though given an incorrect
version number from a semver point of view.

Had we given 1.1.0 and so on semantically correct version numbers, we
would have versioned like this:

1.1.0 => 2.0.0  (MAJOR release, has API incompatibili

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

[Matt Caswell]

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.

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

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

[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

[Tim Hudson]

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

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