[openssl-project] Release strategy updates & other policies

[Paul Dale]

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

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.

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.

Some thoughts about this:
Should we deprecate functions at a major release or with LTS releases?  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?
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?
Does it make sense to announce APIs that will be deprecated one release cycle ahead of doing so?

Macro deprecation might need to be slightly different.


Do we have a policy for API changes?  Have we defined what an API change is?
I like a distinction between adding a new API and changing an existing one.  Putting the latter to a vote seems sensible, the former probably doesn't need it so long as too many don't start appearing.

Would an API deprecation be considered a change?  I'd think not if there is a deprecation policy and it is followed.
Does defining otherwise undefined behaviour constitute a change in the API?
Does documenting undefined behaviour constitute a change in the API?
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.


Pauli
-- 
Oracle
Dr Paul Dale | Cryptographer | Network Security & Encryption 
Phone +61 7 3031 7217
Oracle Australia


-----Original Message-----
From: Matt Caswell [mailto:matt at openssl.org] 
Sent: Friday, 21 September 2018 11:19 PM
To: openssl-project at openssl.org
Subject: [openssl-project] Release strategy updates

I am very concerned about stability of our API moving forwards. There are various discussions about changing the version number to 1.2.0 (or possibly 2.0.0) - which according to our versioning scheme would allow breaking changes. Whilst this is true I think we need to be very wary about "opening the flood gates" for breaking changes.

The move from 1.0.x to 1.1.0 was hard on our users and we should avoid that again.

With that in mind I have opened the following PR (based largely on wording suggested by Viktor):

https://github.com/openssl/web/pull/82

At the same time I have taken the opportunity to clean up some out-of-date stuff in the release strategy.

This is independent of the semantic versioning discussion which may itself see further changes being made to the release strategy.

Thoughts?

Matt
_______________________________________________
openssl-project mailing list
openssl-project at openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project