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: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
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@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project
___
openssl-project mailing list
openssl-project@openssl.org
https://mta.openssl.org/mailman/listinfo/openssl-project
