Post-migration Devguide reorganization

[ezio-melotti]

I think the Devguide is due for some reorganization after the migration.

In particular:

• The version control setup section should link to a separate "git" page (either the pullrequest or the committing page -- see below). (see Update the setup and PR lifecycle pages #265)
• The compile and build section should be reorganized. (see Reorganize the setup.rst page. #412)
• The lifecycle of a PR page seems to expand on the quick start, but doesn't include detailed setup instructions and git commands. This page seem to be aimed at contributors (see Update the setup and PR lifecycle pages #265). Also the Generation section should be under Preparation, alongside another subsection about running tests.
• The runtests page expands on a paragraph pullrequest/preparation.
• The silence warnings and fixing easy issues are both 2-paragraphs pages that might be moved as sections of other pages.
• The tracker and triaging page should be updated and perhaps merged (see Update the devguide with the discussion on bug triage #308 and Update triage page with tables #339).
• The where to get help and following Python's development could be merged.
• The committing page seems to be aimed to core-dev, but since now the workflow for both core devs and contributors is quite similar, it should perhaps be merged with the pullrequest page. Parts of this page should be moved to other pages, and only the content relevant to core devs should be left there. (see Update wording on committing.rst. #262 and Reorganize git commands #263)
• The continuous integration page should be updated. (see Update buildslave.rst page for Buildbot 0.9.x #290)
• The experts page should be moved closer to the developers page. (see Reorganise the devguide to directories  #901)
• The mercurial for git developers page is now unnecessary, and it should either be removed, or better reversed and become "git for mercurial developers". (see Delete the "Mercurial for git developers" page #258)
• The adding to the stdlib page should first list what are good and bad addictions (with examples) and then explain the process to add something (see Idea: mention 3rd party "extended stdlib" modules in developer guide #35).

The other pages don't have any major issue :)

[Mariatta]

Perhaps we can create smaller issues to address each items, and create a new GitHub project for this :)

[ezio-melotti]

I wanted to gather some initial feedback before starting working on this, then I think I can start proposing PRs addressing each point. It should be fine to discuss on the PRs rather than opening new issues, but if issues are better I'm not against using this as a meta-issue and opening other issues for each point.
I'm not familiar with GitHub projects, but I guess we can try. One problem is that several of these are related with each other, so they can't be addressed individually.

[willingc]

Perhaps make the bullet list into a checklist. The individual items could then be checked off as individual PRs address one or more of the items.

[brettcannon]

The other option for managing this is to create a project and add the appropriate PRs and issues as they come up, but checkboxes were already added so that's obviously the simplest. 😄

[willingc]

@ezio-melotti The project related to this was completed. Do you want to close this issue or migrate the outstanding items in the checklist to their own individual issues (making them more bite-size for contributors)?

[ezio-melotti]

I didn't have time to work on this lately, but I would like to keep it around for the next time I do.
I've been trying to keep the checklist updated as other issues gets addressed, and -- at least to me -- it provides a good overview of the status of the Devguide and what should still be reviewed/updated.

[willingc]

Sounds good @ezio-melotti. Thanks for the update. 👍

As an FYI, I went through and triaged all of the issues on the devguide, labeled them, and provided next actions, when able.

[hugovk]

This issue hasn't been updated in 6 years. There was a re-org 2 years ago (#901).

The re-org also means it's hard to verify what's remaining because the OP links are now 404.

Is this issue still relevant? If so, please can you check off the done/irrelevant items and update the remaining ones, or close and create new issues? Thanks!

[ezio-melotti]

I now updated the links and a couple of items that got fixed in the meanwhile. There are a few remaining items (copy-pasted from the OP, with additional comments about their current status):

• The runtests page expands on a paragraph pullrequest/preparation.
  • There is now a one-word link to the runtest page, that could be made more explicit (e.g. "See the runtest page for more information.").
• The silence warnings and fixing easy issues are both 2-paragraphs pages that might be moved as sections of other pages.
  • These could still be included in other pages, even though now that we have different top-level sections there is less pressure about reducing the total number of pages.
• The where to get help and following Python's development could be merged.
  • Technically they answer two different questions, but there is some overlapping between the two.
• The continuous integration page should be updated. (see Update buildslave.rst page for Buildbot 0.9.x #290)
  • Someone that is familiar with buildbots should look into this and check if the page is up to date. The fact that it still mentions bbreport (a tool I wrote a decade ago, which might not even work anymore) makes me think that it isn't (at least partially).
• The adding to the stdlib page should first list what are good and bad addictions (with examples) and then explain the process to add something (see Idea: mention 3rd party "extended stdlib" modules in developer guide #35).
  • Now the process is covered for additions to existing modules too, even though it could mirror better the section about adding new modules (which has a specific sub-section about the process). A few examples of recent additions and the process they went through (links to PEPs/discussions/issues/PRs) might still be useful.

[willingc]

@ezio-melotti Would it be helpful to take your bullet points above and make them into individual issues (using GitHub's newish feature to do that)? It might make them more actionable.