devguide Post-migration Devguide reorganization

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

In particular:

[x] The version control setup section should link to a separate "git" page (either the pullrequest or the committing page -- see below). (see #265)
[x] The compile and build section should be reorganized. (see #412)
[x] 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 #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.
[x] The tracker and triaging page should be updated and perhaps merged (see #308 and #339).
[ ] The where to get help and following Python's development could be merged.
[x] 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 #262 and #263)
[ ] The continuous integration page should be updated. (see #290)
[x] The experts page should be moved closer to the developers page. (see #901)
[x] 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 #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 #35).

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

Feb 17 '17 00:02 ezio-melotti

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

Feb 21 '17 21:02 Mariatta

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.

Feb 21 '17 23:02 ezio-melotti

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.

Feb 22 '17 01:02 willingc

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. 😄

Feb 24 '17 23:02 brettcannon

@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)?

Mar 19 '18 13:03 willingc

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.

Mar 19 '18 13:03 ezio-melotti

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.

Mar 19 '18 14:03 willingc

This issue hasn't been updated in 6 years. There was a re-org 2 years ago (https://github.com/python/devguide/pull/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!

Mar 25 '24 20:03 hugovk

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 https://github.com/python/devguide/issues/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 https://github.com/python/devguide/issues/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.

Mar 26 '24 11:03 ezio-melotti

@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.

Mar 27 '24 16:03 willingc