Expand the stakeholders section

[steve-s]

Following my https://github.com/capi-workgroup/problems/pull/66#discussion_r1278003878

[steve-s]

Fixed the review comment and two other minor things/typos I spotted in the meanwhile

[hodgestar]

Is it even correct to say that CPython Core (excluding stdlib extensions) is using the cpython API? It can access whatever it wants.

Exactly. However, the "internal C API" and the "extension module C API" overlap substantially, so it seems important to note this distinction clearly somewhere. In the past I have been in some confusing discussions because I was thinking of the C API as "for extension modules" and others in the discussion have been thinking of them as "for writing CPython". Given the overlap, it's hard to criticize this latter view as entirely incorrect.

I'm happy for this to be resolved by defining what we mean by "C API" in these documents to exclude the internal use instead. As already noted by @iritkatriel, the internal API can, to zeroth approximation, be whatever it wants because it is internal.

[steve-s]

That’s still a rather large addition to a doc that exists to summarize the issues, not to debate them.

Which parts of the addition do you see as "debating" rather then "describing"?

I think the additions really boil down to:

1. Backwards/forwards compatibility of API and ABI is a problem of the current C API (for external parties that need to maintain extensions).
2. CPython developers should be listed as stakeholders, because they use the API internally and must maintain its public contract
3. Current stable ABI and to some extent limited API are problem for internal development of CPython

Plus this PR also expands on different use-cases of why and how users choose to develop C extensions. Let's put that aside for now to keep this discussion more focused.

Do we agree on points 1. - 3.? I can make the CPython developers section shorter. I would like to keep the compatibility requirements in the stakeholders section (I think that's already short). I'd leave out the use-cases for extension writing. Does that sound better?

[gvanrossum]

Ceretainly this comment feels like debating. :-)

I feel it's redundant to list the CPython developers as stakeholders -- that's implied. When they use the API, they are just users (like extension authors). When they design parts of the API, they consult this document (or its successors, etc.). None of that needs to be said or described explicitly, that just makes the document longer.

I would be very surprised if backward and forward compatibility wasn't already mentioned in the document. It's an obvious requirement (without it, we wouldn't be so stressed about changes to the C API), we don't need to use many words.

Indeed the Stable ABI is a constraint, if it isn't mentioned at all in the document we could add a sentence mentioning it.

[steve-s]

Ok, point taken.

CPython developers as stakeholders: that's indeed implied. I wanted to emphasize it. If this document is intended for CPython developers (and not extension authors, for example), than there's no point in emphasizing that.

Points 2. and 3. are indeed mentioned later in the document. I wanted to emphasize the connection between problems and the stakeholders.

I still feel that there is ambiguity in what we actually mean by C API and whether the document is describing problems with the API that is public and intended to be consumed by external project (extensions) or also problems with CPython's internal abstractions that are AFAICS mixed together with the public C API, which I think increases the possibility of confusion. Similar to @hodgestar, I have also occasionally found that in certain discussions, it isn't always clear which API each party is referring to.

Now I suggest just changing the introduction:

- This document describes our shared view of the C API, with...
+ This document describes our shared view of the public C API intended to be consumed by external parties, with...

as long as this is what this document should describe?

[gvanrossum]

- This document describes our shared view of the C API, with... 
+ This document describes our shared view of the public C API intended to be consumed by external parties, with...

Given that you somehow were confused about whether that's what was meant by "C API", I can't argue against this change (if it's the only change you now propose). To be clear, the intended readers of this document are those core developers who are in charge of maintaining and (re)designing the (public) C API (including the Steering Council, which has the ultimate authority -- though they very much prefer rough consensus among core developers to appear without their intervention). We want to hear from stakeholders, to make sure that they are heard; but this document is not intended for extension authors who just want to know about the C API or its future directions (as the document itself takes no position on the latter -- its intention is to inform the deciders). Considerations about priorities, for example, is in our future, but should not be included in this document. (The problem is definitely over-constrained, so setting priorities will be essential if we want to make decisions; but this document is not the place to state those priorities.)

[steve-s]

I've created a new PR for the change that we seem to be in agreement on