> The idea being that supporting existing users means not changing > the existing API, whereas catering to new users means working > towards a new fresh consistent API. OpenSSL has been in use for getting on for 20 years (I think) and may still be in use in another 20 years, so can not stay still to make life easy for old projects, it has to evolve for new projects, as it does. But any changes should be clearly documented and should not require the use of third party sites like ABI to discover new APIs and changes to old ones. Major changes are usually in the changelog, but can be hard to find when updating from a much earlier release. There should really be detailed articles about upgrading from any long term release to the latest release, with simple lists of all exports or macros removed or added, or whose use has changed. Also, there is an assumption OpenSSL is only used by other C developers, by the use of public macros that are not usable in any other language. BoringSSL replaced macros with exports and OpenSSL should consider doing the same. Currently changing a macro to an export is rarely documented, so it's hard for those that have rewritten macros in other languages to know something will be broken. There needs to be more task oriented documentation, for instance collecting the APIs needed to create a CSR or certificate, using APIs rather than command line tools which is where much of the documentation currently resides. For instance there is no documentation about building a stack of extensions to add SANs to requests and certificates so a lot of research is needed to adds SANs to a certificate. Angus
