[openssl-project] Release strategy updates & other policies

[Matt Caswell]

On 25/09/18 12:12, Richard Levitte wrote:
> In message <98774a3e-d127-dcd9-c835-3b359d69b449 at openssl.org> on Tue, 25 Sep 2018 11:53:48 +0100, Matt Caswell <matt at openssl.org> said:
> 
>>
>>
>> On 25/09/18 11:48, Richard Levitte wrote:
>>> In message <dee8621c-7071-4bf3-3ce0-dadaff9df682 at openssl.org> on Tue, 25 Sep 2018 11:30:39 +0100, Matt Caswell <matt at openssl.org> said:
>>>
>>>>
>>>>
>>>> On 25/09/18 11:13, Tim Hudson wrote:
>>>>> On Tue, Sep 25, 2018 at 8:07 PM Matt Caswell <matt at openssl.org
>>>>> <mailto:matt at openssl.org>> wrote:
>>>>>
>>>>>     On 25/09/18 10:58, Tim Hudson wrote:
>>>>>     > On Tue, Sep 25, 2018 at 7:23 PM Richard Levitte
>>>>>     <levitte at openssl.org <mailto:levitte at openssl.org>
>>>>>     > <mailto:levitte at openssl.org <mailto:levitte at 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.0....but we already used that number for our
backwards compatible feature release!

Matt



> 
>>> 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 incompatibilities)
>     1.1.1 => 2.1.0	(MINOR release, supposedly has new compatible API)
> 
> Cheers,
> Richard
>