search

python / devguide

The Python developer's guide
https://devguide.python.org/
Creative Commons Zero v1.0 Universal
1.79k stars 735 forks source link

Add a "what's new" page to the devguide #885

Open ezio-melotti opened 2 years ago

ezio-melotti commented 2 years ago

During the last docs-community meeting, we discussed the fact that we are currently using several different tools (git, GitHub, Discourse, Discord, etc.) and each tool has a learning curve. Combined with the fact that the tools change and evolve over time, it's difficult for the devs to use them proficiently and effectively.

Documenting how to use them in the devguide is useful, but devs rarely re-read the devguide to discover these new sections. I therefore propose to create a "What's new" page to list significant additions and changes to the devguide, to make these more discoverable.

I think it will also be useful to post these entries with a regular cadence (e.g. monthly) on Discourse, so that people don't have to actively check the "What's new" page and remember when was the last time they checked.

abdnafees commented 1 year ago

Has this issue been resolved? Can I work on this? I have a few ideas in my mind. It took me a week to infiltrate all community channels including mailing lists, Discourse, and GitHub itself. It took me this long specifically for Discourse notification and email settings and to go through important threads.

terryjreedy commented 1 year ago

In March 2022, the minimum VisualStudio version required to compile Python 3.11 on Windows was upgraded from VS2015, which I had, to VS2017. The next time I compiled, 3.10 worked, 3.11 did not. As I remember, I posted to core mentorship list and then opened an issue. I got 3 or 4 responses that did not fix the problem until someone mentioned the upgraded requirement in June. I have since thought that there should somehow have been a notice of such a critical change in workflow.

abdnafees commented 1 year ago

@terryjreedy I think there needs to be a changelog for changes in tooling, forums, and other community resources. Python is popular and more folks will try to look for like-minded folks so we need to facilitate them.

jeremyhylton commented 1 month ago

We could also distinguish between the tools and the way people use the tools. Git is a great example of that. I read the dev guide this week and followed it to learn how to use git. One section is title "Editing a pull request prior to merging." I got confused here several times, and every time I asked a more experienced developer they said "Oh, I never do that. I do it this way." (Each developer had their own "this way.")

I wasn't clear if code reviews are required, or if people definitely approve them. I wasn't sure if it's okay to take over some else's PR.

So documenting the common patterns of usage of these tools would also help.

terryjreedy commented 1 month ago

Perhaps we should discuss some of the 'this way's on our Discord in the appropriate channels.

Code reviews are generally desired, but not required. This is partly because we do not have enough reviewers. (And you in particular are very welcome back.) I think that reviews are effectively required for 'core' changes. Substantive comments should always be welcome.

PRs by non-codedevs have to be 'taken over' by some coredev who can do the merge. But this can range from do nothing except comment until completely ready, to substantially rewrite. I have done both, and in between, according the the interest and ability of the initial author compared to mine.