Migrate wiki documentation into a ReadTheDocs project?

[ncoghlan]

The tracker development documentation is currently maintained in the Python wiki at https://wiki.python.org/moin/TrackerDevelopment

Might it be worthwhile migrating that into a ReadTheDocs project maintained as part of this repo?

[ncoghlan]

(Note: I wouldn't recommend doing this until #2 is resolved, as importing the python-dev tracker instance is likely to involve wiping any existing history in this repo. That's fine if the only history being list is my creation of the current README.md file, but more of a problem if we have a non-trivial amount of developer documentation here)

[ezio-melotti]

A few comments:

• most of that documentation is not particularly useful if people use the docker image, but it's still good to have somewhere in case someone wants/needs to set up the tracker from scratch;

• the docker image docs is at https://github.com/python/docker-bpo/blob/master/README.md ;

• part of that documentation is probably obsolete and should be revised/removed;

• some of the things required to maintain the tracker are not documented anywhere (I have some personal notes);

• there are two more related wiki pages:

  • https://wiki.python.org/moin/TrackerDevelopmentPlanning which collects a few ideas that could be converted into issues;
  • https://wiki.python.org/moin/DesiredTrackerFeatures which includes more ideas and discussions and could also be converted into issues;

And a few questions:

• What would this docs repo cover (setup, maintenance, others)?
• Should the docker-bpo repo and/or docs be merged with this?
• Should the instances and the docs be separate subrepos?

[willingc]

FWIW the Docker repo works really well to get an environment for development setup. It would be great to move the Dockerfile over here too.

[ncoghlan]

Regarding scope, I personally prefer having developer documentation for a project in the same repo as the project itself. The main cases where I've seen that break down is when the project has a complex branching structure (hence the CPython devguide being separate from CPython itself), or when the documentation covers a broad collection of projects (hence pypa.io and packaging.python.org having their own repos, independent of the project specific docs, as well as https://github.com/python/core-workflow existing as a meta-repo with some discussion of how different tools relate to each other).

I don't think either of those concerns apply here - bugs.python.org should just have a single main line of development, and it's a specific component within the core-workflow umbrella, rather than being a collection of multiple projects itself.