<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On 29 December 2016 at 06:41, Steve Dower <span dir="ltr"><<a href="mailto:steve.dower@python.org" target="_blank">steve.dower@python.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On 28Dec2016 1145, Brett Cannon wrote:<br>
</span><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">
On Tue, 27 Dec 2016 at 12:15 Ronald Oussoren <<a href="mailto:ronaldoussoren@mac.com" target="_blank">ronaldoussoren@mac.com</a><br></span><span class="">
<mailto:<a href="mailto:ronaldoussoren@mac.com" target="_blank">ronaldoussoren@mac.com</a><wbr>>> wrote:<br>
    A directive would make it easier to ensure that the text about the<br>
    stable API is consistent.  I’d also consider adding that directive<br>
    to all API’s that *are* part of the stable API instead of the other<br>
    way around (that would also require changes to …/stable.html). That<br>
    would have two advantages: firstly it makes it easier to document<br>
    from which version an API is part of the stable ABI, and secondly<br>
    forgetting the annotation would imply that an API is not part of the<br>
    stable ABI instead of accidentally claiming to increase the stable ABI.<br>
<br>
<br>
I like Ronald's suggestion of both using a directive and making it for<br>
the stable ABI since it should be an opt-in thing for the API to be<br>
stable instead of opt-out.<br>
</span></blockquote>
<br>
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.<br>
<br>
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.<br></blockquote><div><br></div></div>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.<br><br></div><div class="gmail_extra">That would have a few benefits:<br><br></div><div class="gmail_extra">- if you accidentally add a new function to the stable ABI, you get a test failure<br></div><div class="gmail_extra">- if you deliberately add a new function to the stable ABI, but forget to document it as such, you get a test failure<br></div><div class="gmail_extra">- 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<br><br></div><div class="gmail_extra">(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)<br></div><div class="gmail_extra"><br></div><div class="gmail_extra">Cheers,<br></div><div class="gmail_extra">Nick.<br clear="all"></div><div class="gmail_extra"><br>-- <br><div class="gmail_signature" data-smartmail="gmail_signature">Nick Coghlan   |   <a href="mailto:ncoghlan@gmail.com" target="_blank">ncoghlan@gmail.com</a>   |   Brisbane, Australia</div>
</div></div>