bpo-43795: Document stable_abi.txt format and contents

[encukou]

See discussion here: https://mail.python.org/archives/list/[email protected]/thread/64VOMHNR37N4HVPWAHKHJM4UFYJPVKSV/

(bpo-43795 is closed, but I think reusing it is OK for a comment-only change.)

https://bugs.python.org/issue43795

[encukou]

@gvanrossum, is this the comment you were looking for?

[tiran]

Petr, it would be helpful to explain under which circumstances an entry can be removed -- or that entries cannot be removed, even private _Py APIs.

[encukou]

That's a good idea, but IMO this comment should focus on the specifics of the stable_abi.txt file. So I added a link to the devguide, and I propose a new section there: python/devguide#778

[gvanrossum]

That's a good idea, but IMO this comment should focus on the specifics of the stable_abi.txt file. So I added a link to the devguide, and I propose a new section there: python/devguide#778

Actually I think it should be stated here, in this file, as well. It is much more directly useful here.

[encukou]

I summarized this as "Removing items from this file is generally not allowed, and additions should be considered with that in mind. See the devguide for exact rules."
Otherwise there'd be two fairly complex documents to keep in sync. Or it could all be moved to this file, but I think devguide is a better place.

[gvanrossum]

Thanks! LGTM.