The company I work for uses OpenSSL heavily and we're still on 1.0.2 and looking forward to moving to 1.1.1. It's going to force a lot of code rewriting but this will be cleaner code than we had anyway and cause less bugs.

I think the thing to be looking at when making breaking changes is making sure the OpenSSL team answers the question "Are all possible ways this function could be used have a drop in replacement alternative method of performing them? Ideally with little rewriting of code." If that is handled properly then there shouldn't be as much an issue with making breaking changes. Also any breaking changes that are caused should ideally cause compile time errors/warnings rather than hidden subtle breakages. Renaming functions/creating new ones is better than modifying the functionality of existing ones. In fact I'd prefer a strict "never modify functionality of documented LTS release functions, only remove/deprecate them".

@mlindner The company I work for uses OpenSSL heavily and we're still on 1.0.2 and looking forward to moving to 1.1.1. It's going to force a lot of code rewriting but this will be cleaner code than we had anyway and cause less bugs.

Sure, API changes may be par for the course for a single consumer of the library willing to port a handful of products. The picture is dramatically different for OS distributions with thousands of dependent packages that need to be ported. Since we want to see reasonably rapid uptake of the latest greatest version of OpenSSL, even as we evolve the API, we need to provide much better migration paths than we did from 1.0.2 to 1.1.0. Yes, there are many improvements in 1.1.0, and yes we want users to port to the new way of doing things, but the transitions need to be much less painful, and it should be possible to "just recompile" old code and get it deployed with the new library, and then gradually port to the new way of writing the code. One can test the need for such rewrites by building against a build Configured with "no-deprecated" or definiing OPENSSL_API_COMPAT to the latest version number.

New updates pushed, addressing comments so far

ping?

I updated this to take account of the latest feedback. Please take another look.

I merged the updates proposed in #104 into this PR so we can see the full picture.

Fixup commit pushed addressing all comments received so far with the exception of @kaduk's suggestion of a shorter time period (2 or 3 years) for the deprecation timeout than the 5 years that this text currently says. I've not seen any discussion on that point.

Updates pushed addressing latest feedback. BTW the latest changes imply that we cannot make any more structures opaque until we have documented them as deprecated for 5 years. Do we want to say that?

No. We don't want to be boxed in to leaving a pile of things we planned to sort out and didn't get get to for a much longer time period.

I added an exception for making structures opaque - so the first point now says:

"No existing public interface can be modified except where changes are unlikely to break source compatibility or where structures are made opaque."

BTW, shouldn't this be out of WIP by now?

BTW, shouldn't this be out of WIP by now?

Well I was leaving it in WIP until the OMC vote had concluded.

Ah ok

Taken out of WIP

This has now been approved by the OMC. I added an additional commit to update the release date. Please can I get a reconfirmation on this?

Pushed. Thanks.