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.

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

-----Original Message-----
From: Matt Caswell [mailto:m...@openssl.org] 
Sent: Friday, 21 September 2018 11:19 PM
To: openssl-project@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 

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


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.


openssl-project mailing list
openssl-project mailing list

Reply via email to