I agree that the information here is all useful to document, but also agree with @gvanrossum's comment about the structure of the doc. The purpose of the internals docs is to help contributors navigate the current (this version's) codebase. Rationale for changes should ideally be in the issues that describe the changes.

I think the best approach here would be to document the pre-free-threading implementation, backport it, and then change it to describe the 3.14 implementation (perhaps with links to the issues that discuss the rationale).

The description of the current implementation can include a brief list of the requirements of the implementation:

1. Fast lookup of current task
2. Fast and thread-safe insertion to and deletion from the task set
3. etc...

Then the reader can see that the implementation meets the requirements. But I don't think the current version's document needs to explain that previous implementations didn't meet the requirements.

Also agree with wrapping long lines, as we do in other docs.

I agree that the information here is all useful to document, but also agree with @gvanrossum's comment about the structure of the doc. The purpose of the internals docs is to help contributors navigate the current (this version's) codebase. Rationale for changes should ideally be in the issues that describe the changes.

The current internal docs like interpreter.md describe the current implementation as well as previous implementation which IMO makes it easier to see easily see what all changed so I wrote this doc similarly.

I think the best approach here would be to document the pre-free-threading implementation, backport it, and then change it to describe the 3.14 implementation (perhaps with links to the issues that discuss the rationale). The description of the current implementation can include a brief list of the requirements of the implementation.

I had plans to document more stuff like cancellation semantics at some point, but keeping docs in separate branches would make it harder to determine what exactly changed and sounds like a lot more work to me.

If we only want to keep the current versions docs in here then I think internal docs is the wrong place for this, maybe I should keep it somewhere else?

If we only want to keep the current versions docs in here then I think internal docs is the wrong place for this, maybe I should keep it somewhere else?

It's not that "we only want to keep current versions in this doc", but that we want the focus of this doc to be the current version and not the delta between 3.13 and 3.14 (how will this document evolve when more changes are made in the future?)

The purpose of the internal docs is to help contributors find their way in the codebase. Delta is described in the issues that propose changes.

The current internal docs like interpreter.md describe the current implementation as well as previous implementation which IMO makes it easier to see easily see what all changed so I wrote this doc similarly.

I think you are referring to the sentence "Up through 3.10, the call stack was implemented as a singly-linked list of frame objects. This was expensive because each call would require a heap allocation for the stack frame."

Is there any other reference to previous implementations in interpreter.md? That brief reference to a previous version doesn't make the delta between the versions the focus of the doc in the way that it's done in this PR.

My opinion is only my opinion. @gvanrossum approved the PR, so you can merge it if you think this is a useful way to present the information to future contributors.