On 29 December 2016 at 06:41, Steve Dower <[email protected]> wrote:
> On 28Dec2016 1145, Brett Cannon wrote: > >> On Tue, 27 Dec 2016 at 12:15 Ronald Oussoren <[email protected] >> <mailto:[email protected]>> wrote: >> A directive would make it easier to ensure that the text about the >> stable API is consistent. I’d also consider adding that directive >> to all API’s that *are* part of the stable API instead of the other >> way around (that would also require changes to …/stable.html). That >> would have two advantages: firstly it makes it easier to document >> from which version an API is part of the stable ABI, and secondly >> forgetting the annotation would imply that an API is not part of the >> stable ABI instead of accidentally claiming to increase the stable >> ABI. >> >> >> I like Ronald's suggestion of both using a directive and making it for >> the stable ABI since it should be an opt-in thing for the API to be >> stable instead of opt-out. >> > > The directive is a good idea, but I'm a little concerned about the stable > API being opt-out in the headers and opt-in in the documentation. > > Perhaps we should also figure out the preprocessor gymnastics we need to > make it opt-in in the headers too? Though once we get the build validation > to detect when the stable API changes accidentally it'll be less of an > issue. > Making it opt-in in the documentation could make the build validation easier: check the list from the *docs* against the actual symbols being exported by the headers. That would have a few benefits: - if you accidentally add a new function to the stable ABI, you get a test failure - if you deliberately add a new function to the stable ABI, but forget to document it as such, you get a test failure - if the stable ABI version added directive in the docs doesn't match the stable ABI version used in the headers, you get a test failure (That suggests the tests would need to check the headers with all stable ABI versions from 3.2 up to the current release and ensure they match the current C API documentation) Cheers, Nick. -- Nick Coghlan | [email protected] | Brisbane, Australia
_______________________________________________ Python-Dev mailing list [email protected] https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
