When adding or extending a public C API (including the limited/stable ABI), design signatures and semantics to match established conventions used elsewhere in the ecosystem, and keep documentation perfectly in sync with the actual implementation (e.g., don’t document a size parameter that doesn’t exist yet in the function signature). For functions that have known analogues in other widely-used libraries (e.g., isprime vs. gmpy2’s probabilistic is_probab_prime), explicitly consider and document compatibility expectations so the new API can be used as a drop-in replacement or its differences are clearly called out.
When exposing or checking capsule-based or versioned C APIs, prefer minimal, robust compatibility checks (e.g., magic number and struct size) over strict version-number matching, since exact version checks may be incorrect assumptions for third-party consumers and can unnecessarily break compatibility.
Any change that adds, removes, or modifies a symbol in the limited API must be accompanied by the required bookkeeping: update Misc/stable_abi.txt and run make regen-limited-abi so the stable ABI manifest stays accurate.
Example checklist before merging a new/extended C API:
Misc/stable_abi.txt been updated and make regen-limited-abi been run?