Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Re-examine re-use of the CPython dev guide #9

Open
jeff5 opened this issue Jun 2, 2020 · 1 comment
Open

Re-examine re-use of the CPython dev guide #9

jeff5 opened this issue Jun 2, 2020 · 1 comment

Comments

@jeff5
Copy link
Member

jeff5 commented Jun 2, 2020

I'm convinced we benefit by re-using the CPython guide, but the idea was to track change by pulling in CPython changes as we go along. In practice, this doesn't happen, and when a backlog has built up, the merge looks scary.

Chapters are files. There are three cases to consider:

  1. A file is the same in Jython as in CPython (yay!).
  2. A file has a small number of differences in Jython's copy from CPython's. One might be able to have a file of the same name and merge the changes.
  3. A file differs a lot. Jython needs its own version entirely. (Include here chapters we drop and chapters we add.)

In practice, 2. is where the problem lies, as it's always more important to make a specific change than keep up.

@jeff5
Copy link
Member Author

jeff5 commented Jun 2, 2020

A problem observed with category 3. is as follows. Where there is a "completely different" version of an existing CPython chapter (e.g. runtests_jy.rst replaces runtests.rst) there remains a lot of cross-referencing under the old name (or labels defined in the original). This leads readers into trouble.

It is better not to have both versions around, and to re-use labels (where they mean the same), or invalidate them (which alerts us to dangling references through an error). Corresponding chapters then have the same file name.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant