Process PEP listing the “evolution” guidelines

[encukou]

Now that the C API Workgroup is officially established (PEP-731), we will draft another process PEP, containing guidelines for C API evolution. This PEP is intended as a live document, whose contents continue to be moderated by the workgroup members.

I volunteer to write the first draft.

I intend to keep the terms “evolution” and “revolution” inside this org. The “evolution” PEP will simply be current guidelines for new additions/changes to the C API .

[June 2024] I realized we won't be able to agree on the whole thing at once, so strategy is to add individual sections.

Checklist with the old plan: (click to expand)

• Collect guidelines from this repo into a coherent document
• Remove guidelines that lack consensus (they can be re-added after more discussion)
• Share a draft publicly, remove more guidelines that lack consensus
• Publish and announce the PEP
• Add links to the new PEP to PEP-7

Some outstanding issues in the text:

• In the general public API, these guidelines apply in full force. -- we need a better name for “unlimited” API.
• We should link to a list of the stakeholders somewhere in this document; perhaps we should embed that list in the PEP.
• Figure out what to do with rules for unstable API -- link to PEP-689, or the devguide?
• Can we use this PEP as the new reference for C API guidelines, to expand/change the C API? In short, copy/move this section here: https://devguide.python.org/developer-workflow/c-api/index.html#guidelines-for-expanding-changing-the-public-api
• Document how to expose a function as a symbol in stable ABI, and as a static inline function (or macro) of the same name in non-limited API: https://github.com/capi-workgroup/api-evolution/pull/53/files#r1838797749

[gvanrossum]

That sounds good. Thanks for volunteering!

Note that for the next couple of weeks I'll be traveling and will try to disengage temporarily from the community. I will be back!

[encukou]

The draft PEP isn't done, but I'm getting blind to the issues, and seeing diminishing returns from editing. If you have the time for a rough draft, take a look! I sent it as a PR to my own fork, so you get GitHub's PR UI:

encukou/peps#1

• I didn't remove guidelines that lack consensus. Instead, when talking about something that isn't settled, the guidelines tell you to contact the working group.
• Read the source text, not a rendered version. There are ReST comments with info that (IMO) is only relevant to authors of the guidelines.
• There's (necessarily) some content that doesn't come from issues in this repo. Please take it as new suggestions. I hope it's not too controversial :)
• I haven't yet gone through the issues again to see where consensus is now. But it's generally hard to judge consensus from issue discussion. If you see anything you disagree with, point it out.
• Please don't yet proofread this for grammar (or ReST syntax). Correct a typo if you see it, but focus on organization and content.