In message <79590c7b-98a4-4816-9eea-52f21b5e23e1@default> on Sun, 23 Sep 2018 20:37:46 -0700 (PDT), Paul Dale <paul.d...@oracle.com> said:
> While reading through the lively versioning discussions, it appears > that there are some fundamentals that seem to lack surrounding > policies and guidance. True, we do need some. At the same time, let's be careful not to get too regulated... but we're not quite there, so I'm not worried yet. > 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. It also depends on what the functions are. Quite a few of them are very simple getters and setters, or converters (d2i_ and i2d_ functions, which are documented all in one go), i.e. convenience names that keep the more difficult to use generic functions at bay. It's quite possible that we can find more user friendly ways to generalise a lot of them... > 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. There isn't really one written out, as far as I recall. There is some kind of concensus among some (I have stayed out of it so far, but am obviously getting interested...) > Some thoughts about this: > Should we deprecate functions at a major release or with LTS > releases? I'm not sure I'd tie that to LTS releases specifically. Our current practice (as seen in the name of our deprecation macros) is to deprecate stuff (not just functions... there are certain openssl app commands that I'd like to get rid of) at major release boundary. (Incidently, semantic versioning FAQ suggests that deprecation can as well happen in a minor release, possibly even preceding a major release) Also, we must consider if we see deprecation as an incompatible API change. If we do, deprecation can most certainly only happen at major release boundary. My 0.02 SEK is that we should, if we consider the configuration option 'no-deprecated' and how deprecation at minor release boundary could lead to surprise breakage. > 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? Removal is definitely something we only at major release boundary, and if we continue to do deprecation at major release boundary as well, it means that deprecation and removal are at least a major release away from each other. So the question is what we think we need, or what the users need. The current concensus, last I heard it, is that everything deprecated at 1.1.0 or older will be removed in the next major release. Should we reconsider this? > 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? I'm thinking that as long as we can get the users to think that to reach anything "old" or deprecated, they must link with a legacy library as well, then I think it should happen immediately, i.e. when deprecation starts (incidently, advance deprecation, like we've done with some stuff, will present some build challenges, at least if we want things maximally automated). Frankly, though, I don't think we absolutely need to move deprecated stuff at all. Something to consider is that there might be stuff that we want to remove from public API, but still want to use internally... > Does it make sense to announce APIs that will be deprecated one > release cycle ahead of doing so? Uhmmm, not sure I understand. Isn't deprecation itself an announcement? So announcing it in advance, wouldn't that be something like announcing that we're going to have an announcement soon? > Macro deprecation might need to be slightly different. Why? > Do we have a policy for API changes? Have we defined what an API > change is? No, and not exactly. The FAQ entry on our current versioning scheme has an answer, though, says this: Changes to the middle number are considered major releases and neither source nor binary compatibility is guaranteed. I think that's the closest to a written out definition that we have, and it gives the message that for major releases, any change is fine on principle, while for minor releases, only compatible source changes are allowed (for example, constification of function parameters is fine). Different members have had different opinions on this, though... some have been more strict and said that staying compatible means Do Not Touch Public Headers (except for additions). (I'm not commenting on binary compatibility... you did ask about API, not ABI ;-)) > Would an API deprecation be considered a change? I'd think not if > there is a deprecation policy and it is followed. The 'no-deprecated' configuration option might make you change your mind ;-) > Does defining otherwise undefined behaviour constitute a change in > the API? Good question... one could ask the same question in terms of stability, if something undefined becomes stable, is it less undefined? We could also ask the question in terms of API compatibility. If something undefined becomes defined, is that an API compatible change or not? > Does documenting undefined behaviour constitute a change in the API? Not sure what you mean... if something is undefined and we amend the documentation to say that it's undefined, did the API change at all? > 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. Both are. Are you really asking about compatible vs incompatible API changes? In that case, I agree that the latter is incompatible. Cheers, Richard -- Richard Levitte levi...@openssl.org OpenSSL Project http://www.openssl.org/~levitte/ _______________________________________________ openssl-project mailing list openssl-project@openssl.org https://mta.openssl.org/mailman/listinfo/openssl-project
