[openssl-project] Release strategy updates & other policies

[Richard Levitte]

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?

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

-- 
Richard Levitte         levitte at openssl.org
OpenSSL Project         http://www.openssl.org/~levitte/