[openssl-project] Release strategy updates & other policies

[Richard Levitte]

In message <79590c7b-98a4-4816-9eea-52f21b5e23e1 at default> on Sun, 23 Sep 2018 20:37:46 -0700 (PDT), Paul Dale <paul.dale at oracle.com> said:

> While reading through the lively versioning discussions, it appears
> that there are some fundamentals that seem to lack surrounding
> policies and guidance.

True, we do need some.  At the same time, let's be careful not to get
too regulated...  but we're not quite there, so I'm not worried yet.

> The referenced PR https://github.com/openssl/web/pull/82 starts by
> asking what is our public API?  I'm in the "what's in the header
> files" bucket, which appears to be the consensus.  That's over 5000
> functions and some number of macros.  Is this too many to support
> long term?  I suspect it might be.  The discussion also highlights
> the amount of missing documentation, which is also a concern but not
> the topic here.

It also depends on what the functions are.  Quite a few of them are
very simple getters and setters, or converters (d2i_ and i2d_
functions, which are documented all in one go), i.e. convenience names
that keep the more difficult to use generic functions at bay.

It's quite possible that we can find more user friendly ways to
generalise a lot of them...

> If we have too many APIs, what can we do about it?
> The low level APIs account for about 10% of the total and the FIPS
> project should help clean up some of these.
> 
> That still leaves a lot.  Deprecation seems like a beginning,
> however I've not seen a policy that specifies what or how this is
> done.  Is there one?  If not, it seems prudent to try to create
> one.

There isn't really one written out, as far as I recall.  There is some
kind of concensus among some (I have stayed out of it so far, but am
obviously getting interested...)

> 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'll just use the generic "release" in absence to an answer to this.
> Is it sensible to deprecate functions in one release and remove them
> in the next?  Deprecate and remove two releases later?

Removal is definitely something we only at major release boundary, and
if we continue to do deprecation at major release boundary as well, it
means that deprecation and removal are at least a major release away
from each other.  So the question is what we think we need, or what
the users need.  The current concensus, last I heard it, is that
everything deprecated at 1.1.0 or older will be removed in the next
major release.  Should we reconsider this?

> Would it make more sense to deprecate functions in one release, move
> them to a legacy library in the next and remove them in the third?
> Or even deprecate in the first, move to legacy in the second and let
> them languish there thereafter?

I'm thinking that as long as we can get the users to think that to
reach anything "old" or deprecated, they must link with a legacy
library as well, then I think it should happen immediately, i.e. when
deprecation starts (incidently, advance deprecation, like we've done
with some stuff, will present some build challenges, at least if we
want things maximally automated).

Frankly, though, I don't think we absolutely need to move deprecated
stuff at all.  Something to consider is that there might be stuff that
we want to remove from public API, but still want to use internally...

> Does it make sense to announce APIs that will be deprecated one
> release cycle ahead of doing so?

Uhmmm, not sure I understand.  Isn't deprecation itself an
announcement?  So announcing it in advance, wouldn't that be something
like announcing that we're going to have an announcement soon?

> Macro deprecation might need to be slightly different.

Why?

> Do we have a policy for API changes?  Have we defined what an API
> change is?

No, and not exactly.  The FAQ entry on our current versioning scheme
has an answer, though, says this:

    Changes to the middle number are considered major releases and
    neither source nor binary compatibility is guaranteed.

I think that's the closest to a written out definition that we have,
and it gives the message that for major releases, any change is fine
on principle, while for minor releases, only compatible source changes
are allowed (for example, constification of function parameters is
fine).
Different members have had different opinions on this, though...  some
have been more strict and said that staying compatible means Do Not
Touch Public Headers (except for additions).

(I'm not commenting on binary compatibility...  you did ask about API,
not ABI ;-))

> Would an API deprecation be considered a change?  I'd think not if
> there is a deprecation policy and it is followed.

The 'no-deprecated' configuration option might make you change your
mind ;-)

> Does defining otherwise undefined behaviour constitute a change in
> the API?

Good question...  one could ask the same question in terms of
stability, if something undefined becomes stable, is it less
undefined?

We could also ask the question in terms of API compatibility.  If
something undefined becomes defined, is that an API compatible change
or not?

> Does documenting undefined behaviour constitute a change in the API?

Not sure what you mean...  if something is undefined and we amend the
documentation to say that it's undefined, did the API change at all?

> While I wouldn't consider adding a NULL check to be an API change,
> but what about removing one?  I'd think the latter is.

Both are.  Are you really asking about compatible vs incompatible API
changes?  In that case, I agree that the latter is incompatible.

Cheers,
Richard

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