Project direction

[Angus Robertson - Magenta Systems Ltd]

> 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