[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 <matt at openssl.org
> <mailto:matt at openssl.org>> 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.0....but 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