On 29 December 2016 at 06:41, Steve Dower <steve.do...@python.org> wrote:
> On 28Dec2016 1145, Brett Cannon wrote: > >> On Tue, 27 Dec 2016 at 12:15 Ronald Oussoren <ronaldousso...@mac.com >> <mailto:ronaldousso...@mac.com>> 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 | ncogh...@gmail.com | Brisbane, Australia
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
