[harshitethic]

Addresses #47.

Summary

• explain API as the source-level contract and ABI as the binary-level contract
• connect ABI compatibility to CPython minor versions and platforms
• point readers to the Limited API / Stable ABI and abi3 wheels

Validation

• documentation-only change
• isolated one-file diff against the current guide

---

📚 Documentation preview 📚: https://python-packaging-user-guide--2145.org.readthedocs.build/en/2145/

[ncoghlan]

Thanks for this! The updated content is good, but it highlights the fact that the current paragraph is really in the wrong place (as it applies to all extension modules, not just those written to wrap external libraries). We should move it up to a better location rather than leaving it where it is.

[harshitethic]

Updated in response to the review: the API vs ABI explanation (including Limited API / abi3) now appears under a new How binary extension modules work heading in the general overview, immediately after Disadvantages. The wrapper subsection now only discusses the specific burden of maintaining wrappers. Commit d1ffa35.

AI-assisted edit; checked that the explanation appears once and the existing RST references remain intact. A full Sphinx build has not yet been run.

[merwok]

This project has a lot of open issues, and a small number of people who triage or review.

I am not sure that firing a chatbot to open a lot of PRs is a useful use of everyone’s time. It would be better to have contributors develop human knowledge on the issues and think holistically. Here for example: how should the whole page be reworked? There are a few tickets about various small things (broken link here, definition of API/ABI there) but in the big picture, we have multiple capable build backends, multiple bindings/wrappers generators, dedicated guides like pypackaging-native that we could link to.

How to consider all that to make a great useful page for our guide’s readers? That would be a valuable contribution.

[ncoghlan]

Couple of minor edit suggestions (specifically addressing the comment @merwok made about "minor release" vs "feature release"). I'll apply those directly before merging (since they can be handle via the sugggestions UI, unlike the larger structural edit I requested last time).

[ncoghlan]

This project has a lot of open issues, and a small number of people who triage or review.

I am not sure that firing a chatbot to open a lot of PRs is a useful use of everyone’s time. It would be better to have contributors develop human knowledge on the issues and think holistically. Here for example: how should the whole page be reworked? There are a few tickets about various small things (broken link here, definition of API/ABI there) but in the big picture, we have multiple capable build backends, multiple bindings/wrappers generators, dedicated guides like pypackaging-native that we could link to.

How to consider all that to make a great useful page for our guide’s readers? That would be a valuable contribution.

While I somewhat agree with this perspective, contemplating those larger rewrites (or even figuring out how to appropriately reference third party resources like https://pydevtools.com/) is a genuinely hard problem because "Is this change better than the status quo?" is so hard to define in the general case.

Smaller PRs like this one (where the answer to "Is it better?" is quite obviously "Yes!") are a much simpler prospect to review, especially when the submitter is responsive to feedback and patient with the fact that getting (and keeping) a reviewer's attention involves a certain element of luck.

Self-prioritising is definitely a good thing to do, though (CPython recently had to impose a per-contributor limit on open PRs to address problems with folks opening lots of PRs at once, for example)