Re: API compatibility promises in light of biannual releases (was: Re: Intentions for 1.11 release timing)

Daniel Shahaf wrote on 2018-06-29:
> Julian Foad wrote on Fri, Jun 22, 2018:
> > Another angle on this: I interpret what we are doing as inserting extra
> > mini-feature-releases into the existing cycle, rather than compressing the
> > existing cycle to happen four times faster.
>
> I wonder what our API compatibility promises would be in the new scheme.
>
> In terms of the proposed scheme, we currently do only LTS releases, and once an
> API appears in an LTS .0 release it will remain supported until the subsequent
> major release, i.e., practically forever.
>
> I assume our API current compatibility promises would apply unchanged to any
> APIs that appear in LTS releases. However, I'm not sure we necessarily want to
> offer the same promises to APIs that (first) appear in biannual releases,
> because those APIs will have had less time to mature (in design / review /
> deployment).
>
> As an example, perhaps APIs new in a biannual release should only be supported
> until the subsequent LTS release? Then, once an API makes its first appearance
> in a biannual release, if it's a good API we include it in the subsequent LTS
> and it's set in stone, but if needs some tweaks we aren't obliged to support
> the original version forever.

A policy that forces new APIs to be set in stone at their first release is a hindrance. At the same time, it is important to follow a clear versioning specification. We currently seem to match Semantic Versioning http://semver.org although we don't explicitly reference it. This says the minor release number indicates backward-compatible additions and changes, and the major number must be incremented if we make incompatible changes. I don't think we want to be removing APIs and bumping the major number on our LTS releases.

> Or perhaps we just need to be more disciplined about properly marking APIs as
> "experimental" (doxygen "@experimental" annotations and SVN_EXPERIMENTAL
> preprocessor annotations) when they are objectively not yet mature.

I don't think marking things as experimental is a very good approach when applied "ad hoc". It is easy to mark something as experimental initially and then never review and upgrade or remove it, leaving its users in limbo.

However, a process of marking all new APIs as experimental in regular releases, and ensuring we review them for LTS releases, might be a good way to satisfy both Semantic Versioning and experimental APIs.

That is my best suggestion.

-- 
- Julian