From 9b33152b31682295884defc144f2c391457951aa Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 9 Sep 2024 14:40:06 -0700 Subject: [PATCH 1/8] Add proposed outline for contrib.python.org guide --- contrib_outline.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 contrib_outline.md diff --git a/contrib_outline.md b/contrib_outline.md new file mode 100644 index 0000000000..06ae545123 --- /dev/null +++ b/contrib_outline.md @@ -0,0 +1,71 @@ + + +# Outline for Contributor’s Guide + +**DRAFT** + +After thinking about how to create a documentation contribution guide from the devguide, I think it makes more sense to have one Contributor’s Guide with explicit sections for code and docs. + +Here is a quick outline of how it could be structured. “(from devguide)” means to use that section from the current devguide verbatim. + +* Introduction + * Importance of healthy inclusive collaboration (While code is a large part of the project's success, project management, documentation, governance, sprint outreach, etc. matter). We respect the individual skills people bring to the project and strive to create and maintain a culture of inclusion. + * About this guide + * Types of contribution (Pathways for Contributors) + * Helping with the Contributors' Guide +* The CPython project + * Structure + * CoC + * Standard for communication + * Enforcement details + * Roles + * Core teamdevelopers (from devguide) + * (SC?) (EB?) + * Triager + * Contributors + * types of contributions, role of each contributors + * Governance + * (SC?) (EB?) + * Other WG? Typing council? C-API WG? + * GitHub + * Main CPython rRepos + * Core workflow repos + * Infrastructure repos + * Communication channels + * Repos + * Discourse + * Discord + * Mailing lists (deprioritize) + * Where to get help + * Issue triaging + * (How exactly? Guidelines? Is it just about applying labels?) + * Easy issues + * (should triagers assign reviewers?) + * (should triagers close issues?) + * (Reviewing) + * How? Etiquette? + * How to request a review? + * Where to get help +* Getting started + * Basic setup + * Git bootcamp (simplified for everyone to use) +* Code contributions + * Code setup and building (more complex stuff, delta from basic setup above) + * More git bootcamp (patches, etc) + * Lifecycle of a code pull request + * Development workflow (from devguide) + * Testing and buildbots (from devguide) + * Development tools (from devguide) + * CPython’s internals (from devguide) + * Code style guide +* Documentation contributions + * Lifecycle of a docs pull request + * (pull in Documentation sections from devguide) + * Rst/Sphinx bootcamp + * Editorial Style Guide +* Translation + * Need details +* Accessibility and user success +* Security and infrastructure + * Core Team Resources (from the devguide: I think we should reevaluate if it still makes sense to have the "How to become a core developer" section in this guide and in this particular section.) + From fc3b2288881c29dc4b46cf35fe3483893c92abb8 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 9 Sep 2024 14:54:38 -0700 Subject: [PATCH 2/8] Create contrib folder and index file --- contrib/index.rst | 74 +++++++++++++++++++++++++++++++++++++++++++++++ index.rst | 1 + 2 files changed, 75 insertions(+) create mode 100644 contrib/index.rst diff --git a/contrib/index.rst b/contrib/index.rst new file mode 100644 index 0000000000..cf9ca3892c --- /dev/null +++ b/contrib/index.rst @@ -0,0 +1,74 @@ +========================== +Python Contributor's Guide +========================== + +This guide is a comprehensive resource for contributing to Python. + +.. _proposed_contents: + +Proposed Contents +----------------- + +* Introduction + * Importance of healthy inclusive collaboration (While code is a large part of the project's success, project management, documentation, governance, sprint outreach, etc. matter). We respect the individual skills people bring to the project and strive to create and maintain a culture of inclusion. + * About this guide + * Types of contribution (Pathways for Contributors) + * Helping with the Contributors' Guide +* The CPython project + * Structure + * CoC + * Standard for communication + * Enforcement details + * Roles + * Core teamdevelopers (from devguide) + * (SC?) (EB?) + * Triager + * Contributors + * types of contributions, role of each contributors + * Governance + * (SC?) (EB?) + * Other WG? Typing council? C-API WG? + * GitHub + * Main CPython rRepos + * Core workflow repos + * Infrastructure repos + * Communication channels + * Repos + * Discourse + * Discord + * Mailing lists (deprioritize) + * Where to get help + * Issue triaging + * (How exactly? Guidelines? Is it just about applying labels?) + * Easy issues + * (should triagers assign reviewers?) + * (should triagers close issues?) + * (Reviewing) + * How? Etiquette? + * How to request a review? + * Where to get help +* Getting started + * Basic setup + * Git bootcamp (simplified for everyone to use) +* Code contributions + * Code setup and building (more complex stuff, delta from basic setup above) + * More git bootcamp (patches, etc) + * Lifecycle of a code pull request + * Development workflow (from devguide) + * Testing and buildbots (from devguide) + * Development tools (from devguide) + * CPython’s internals (from devguide) + * Code style guide +* Documentation contributions + * Lifecycle of a docs pull request + * (pull in Documentation sections from devguide) + * Rst/Sphinx bootcamp + * Editorial Style Guide +* Translation + * Need details +* Accessibility and user success +* Security and infrastructure + * Core Team Resources (from the devguide + + + diff --git a/index.rst b/index.rst index b385b1ee1b..c10736a474 100644 --- a/index.rst +++ b/index.rst @@ -315,6 +315,7 @@ Full table of contents core-developers/index internals/index versions + contrib/index .. _Buildbot status: https://www.python.org/dev/buildbot/ .. _Misc directory: https://github.com/python/cpython/tree/main/Misc From 80810dbf649d93129cdcea037528d7b81f1f54aa Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 9 Sep 2024 15:48:11 -0700 Subject: [PATCH 3/8] Add stub pages for guide --- conf.py | 6 ++++++ contrib/code.rst | 18 +++++++++++++++++ contrib/doc.rst | 15 ++++++++++++++ contrib/get-started.rst | 13 ++++++++++++ contrib/index.rst | 32 ++++++++++++++++++++++++------ contrib/intro.rst | 15 ++++++++++++++ contrib/outreach.rst | 12 +++++++++++ contrib/project.rst | 43 ++++++++++++++++++++++++++++++++++++++++ contrib/security.rst | 13 ++++++++++++ contrib/translation.rst | 12 +++++++++++ contrib/user-success.rst | 14 +++++++++++++ 11 files changed, 187 insertions(+), 6 deletions(-) create mode 100644 contrib/code.rst create mode 100644 contrib/doc.rst create mode 100644 contrib/get-started.rst create mode 100644 contrib/intro.rst create mode 100644 contrib/outreach.rst create mode 100644 contrib/project.rst create mode 100644 contrib/security.rst create mode 100644 contrib/translation.rst create mode 100644 contrib/user-success.rst diff --git a/conf.py b/conf.py index fc46f32234..2c93107e9a 100644 --- a/conf.py +++ b/conf.py @@ -166,6 +166,12 @@ # sphinx-notfound-page notfound_urls_prefix = "/" +# prolog and epilogs +rst_prolog = """ +.. |draft| replace:: **Draft** of Python Contributor's Guide +.. |purpose| replace:: See more info about the contributor guide in Discourse. Questions? Ask the docs editorial board. +""" + # sphinx.ext.extlinks # This config is a dictionary of external sites, # mapping unique short aliases to a base URL and a prefix. diff --git a/contrib/code.rst b/contrib/code.rst new file mode 100644 index 0000000000..3504233a9f --- /dev/null +++ b/contrib/code.rst @@ -0,0 +1,18 @@ +================== +Code contributions +================== + +.. important:: + + |draft| + + |purpose| + +* Code setup and building (more complex stuff, delta from basic setup above) +* More git bootcamp (patches, etc) +* Lifecycle of a code pull request +* Development workflow (from devguide) +* Testing and buildbots (from devguide) +* Development tools (from devguide) +* CPython’s internals (from devguide) +* Code style guide \ No newline at end of file diff --git a/contrib/doc.rst b/contrib/doc.rst new file mode 100644 index 0000000000..456a2b93de --- /dev/null +++ b/contrib/doc.rst @@ -0,0 +1,15 @@ +=========================== +Documentation contributions +=========================== + +.. important:: + + |draft| + + |purpose| + + +* Lifecycle of a docs pull request +* (pull in Documentation sections from devguide) +* Rst/Sphinx bootcamp +* Editorial Style Guide \ No newline at end of file diff --git a/contrib/get-started.rst b/contrib/get-started.rst new file mode 100644 index 0000000000..646357372e --- /dev/null +++ b/contrib/get-started.rst @@ -0,0 +1,13 @@ +=============== +Getting started +=============== + +.. important:: + + |draft| + + |purpose| + + +* Basic setup +* Git bootcamp (simplified for everyone to use) \ No newline at end of file diff --git a/contrib/index.rst b/contrib/index.rst index cf9ca3892c..455891b7c0 100644 --- a/contrib/index.rst +++ b/contrib/index.rst @@ -1,9 +1,30 @@ -========================== -Python Contributor's Guide -========================== +================================== +Python Contributor's Guide (draft) +================================== + +.. important:: + + |draft| + + |purpose| + This guide is a comprehensive resource for contributing to Python. +.. toctree:: + :maxdepth: 2 + + intro + project + get-started + code + doc + translation + user-success + security + outreach + + .. _proposed_contents: Proposed Contents @@ -69,6 +90,5 @@ Proposed Contents * Accessibility and user success * Security and infrastructure * Core Team Resources (from the devguide - - - +* Outreach + * Sprints diff --git a/contrib/intro.rst b/contrib/intro.rst new file mode 100644 index 0000000000..7922641014 --- /dev/null +++ b/contrib/intro.rst @@ -0,0 +1,15 @@ +============ +Introduction +============ + +.. important:: + + |draft| + + |purpose| + + +* Importance of healthy inclusive collaboration (While code is a large part of the project's success, project management, documentation, governance, sprint outreach, etc. matter). We respect the individual skills people bring to the project and strive to create and maintain a culture of inclusion. +* About this guide +* Types of contribution (Pathways for Contributors) +* Helping with the Contributors' Guide \ No newline at end of file diff --git a/contrib/outreach.rst b/contrib/outreach.rst new file mode 100644 index 0000000000..d43aa8e9de --- /dev/null +++ b/contrib/outreach.rst @@ -0,0 +1,12 @@ +======== +Outreach +======== + +.. important:: + + |draft| + + |purpose| + + +* Sprints diff --git a/contrib/project.rst b/contrib/project.rst new file mode 100644 index 0000000000..062f7cfd5b --- /dev/null +++ b/contrib/project.rst @@ -0,0 +1,43 @@ +=================== +The CPython project +=================== + +.. important:: + + |draft| + + |purpose| + + +* Structure +* CoC + * Standard for communication + * Enforcement details +* Roles + * Core teamdevelopers (from devguide) + * (SC?) (EB?) + * Triager + * Contributors + * types of contributions, role of each contributors +* Governance + * (SC?) (EB?) + * Other WG? Typing council? C-API WG? +* GitHub + * Main CPython rRepos + * Core workflow repos + * Infrastructure repos +* Communication channels + * Repos + * Discourse + * Discord + * Mailing lists (deprioritize) + * Where to get help +* Issue triaging + * (How exactly? Guidelines? Is it just about applying labels?) + * Easy issues + * (should triagers assign reviewers?) + * (should triagers close issues?) +* (Reviewing) + * How? Etiquette? + * How to request a review? +* Where to get help \ No newline at end of file diff --git a/contrib/security.rst b/contrib/security.rst new file mode 100644 index 0000000000..ef75c15053 --- /dev/null +++ b/contrib/security.rst @@ -0,0 +1,13 @@ +========================================= +Security and infrastructure contributions +========================================= + +.. important:: + + |draft| + + |purpose| + +* Security +* Infrastructure +* Core workflow \ No newline at end of file diff --git a/contrib/translation.rst b/contrib/translation.rst new file mode 100644 index 0000000000..fc8b736816 --- /dev/null +++ b/contrib/translation.rst @@ -0,0 +1,12 @@ +=========== +Translation +=========== + +.. important:: + + |draft| + + |purpose| + +* How to add a new language +* Tools and workflow \ No newline at end of file diff --git a/contrib/user-success.rst b/contrib/user-success.rst new file mode 100644 index 0000000000..79b6f926e7 --- /dev/null +++ b/contrib/user-success.rst @@ -0,0 +1,14 @@ +======================================= +Accessibility, design, and user success +======================================= + +.. important:: + + |draft| + + |purpose| + + +* Accessibility +* Design +* User success \ No newline at end of file From 37e447d8c970f6ae7ca80ce5c0e8db890068ce95 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 9 Sep 2024 15:52:12 -0700 Subject: [PATCH 4/8] add newline --- contrib/user-success.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contrib/user-success.rst b/contrib/user-success.rst index 79b6f926e7..2a9ef5d4e5 100644 --- a/contrib/user-success.rst +++ b/contrib/user-success.rst @@ -11,4 +11,4 @@ Accessibility, design, and user success * Accessibility * Design -* User success \ No newline at end of file +* User success From 191bc8bb1d86a5cda026e6abdda00715c1ba49b4 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 9 Sep 2024 15:55:33 -0700 Subject: [PATCH 5/8] add trailing newline for all stubs --- contrib/code.rst | 2 +- contrib/doc.rst | 2 +- contrib/get-started.rst | 2 +- contrib/intro.rst | 2 +- contrib/project.rst | 2 +- contrib/security.rst | 2 +- contrib/translation.rst | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/contrib/code.rst b/contrib/code.rst index 3504233a9f..6c23c3a87a 100644 --- a/contrib/code.rst +++ b/contrib/code.rst @@ -15,4 +15,4 @@ Code contributions * Testing and buildbots (from devguide) * Development tools (from devguide) * CPython’s internals (from devguide) -* Code style guide \ No newline at end of file +* Code style guide diff --git a/contrib/doc.rst b/contrib/doc.rst index 456a2b93de..133719d6e2 100644 --- a/contrib/doc.rst +++ b/contrib/doc.rst @@ -12,4 +12,4 @@ Documentation contributions * Lifecycle of a docs pull request * (pull in Documentation sections from devguide) * Rst/Sphinx bootcamp -* Editorial Style Guide \ No newline at end of file +* Editorial Style Guide diff --git a/contrib/get-started.rst b/contrib/get-started.rst index 646357372e..84c5afd707 100644 --- a/contrib/get-started.rst +++ b/contrib/get-started.rst @@ -10,4 +10,4 @@ Getting started * Basic setup -* Git bootcamp (simplified for everyone to use) \ No newline at end of file +* Git bootcamp (simplified for everyone to use) diff --git a/contrib/intro.rst b/contrib/intro.rst index 7922641014..f0953ebbee 100644 --- a/contrib/intro.rst +++ b/contrib/intro.rst @@ -12,4 +12,4 @@ Introduction * Importance of healthy inclusive collaboration (While code is a large part of the project's success, project management, documentation, governance, sprint outreach, etc. matter). We respect the individual skills people bring to the project and strive to create and maintain a culture of inclusion. * About this guide * Types of contribution (Pathways for Contributors) -* Helping with the Contributors' Guide \ No newline at end of file +* Helping with the Contributors' Guide diff --git a/contrib/project.rst b/contrib/project.rst index 062f7cfd5b..09f545a353 100644 --- a/contrib/project.rst +++ b/contrib/project.rst @@ -40,4 +40,4 @@ The CPython project * (Reviewing) * How? Etiquette? * How to request a review? -* Where to get help \ No newline at end of file +* Where to get help diff --git a/contrib/security.rst b/contrib/security.rst index ef75c15053..db40b4a167 100644 --- a/contrib/security.rst +++ b/contrib/security.rst @@ -10,4 +10,4 @@ Security and infrastructure contributions * Security * Infrastructure -* Core workflow \ No newline at end of file +* Core workflow diff --git a/contrib/translation.rst b/contrib/translation.rst index fc8b736816..b337fb6ff6 100644 --- a/contrib/translation.rst +++ b/contrib/translation.rst @@ -9,4 +9,4 @@ Translation |purpose| * How to add a new language -* Tools and workflow \ No newline at end of file +* Tools and workflow From ac0096a2066fc690bebcdf0b4f2d781e622fc5b2 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 9 Sep 2024 15:58:01 -0700 Subject: [PATCH 6/8] remove markdown file of outline --- contrib_outline.md | 71 ---------------------------------------------- 1 file changed, 71 deletions(-) delete mode 100644 contrib_outline.md diff --git a/contrib_outline.md b/contrib_outline.md deleted file mode 100644 index 06ae545123..0000000000 --- a/contrib_outline.md +++ /dev/null @@ -1,71 +0,0 @@ - - -# Outline for Contributor’s Guide - -**DRAFT** - -After thinking about how to create a documentation contribution guide from the devguide, I think it makes more sense to have one Contributor’s Guide with explicit sections for code and docs. - -Here is a quick outline of how it could be structured. “(from devguide)” means to use that section from the current devguide verbatim. - -* Introduction - * Importance of healthy inclusive collaboration (While code is a large part of the project's success, project management, documentation, governance, sprint outreach, etc. matter). We respect the individual skills people bring to the project and strive to create and maintain a culture of inclusion. - * About this guide - * Types of contribution (Pathways for Contributors) - * Helping with the Contributors' Guide -* The CPython project - * Structure - * CoC - * Standard for communication - * Enforcement details - * Roles - * Core teamdevelopers (from devguide) - * (SC?) (EB?) - * Triager - * Contributors - * types of contributions, role of each contributors - * Governance - * (SC?) (EB?) - * Other WG? Typing council? C-API WG? - * GitHub - * Main CPython rRepos - * Core workflow repos - * Infrastructure repos - * Communication channels - * Repos - * Discourse - * Discord - * Mailing lists (deprioritize) - * Where to get help - * Issue triaging - * (How exactly? Guidelines? Is it just about applying labels?) - * Easy issues - * (should triagers assign reviewers?) - * (should triagers close issues?) - * (Reviewing) - * How? Etiquette? - * How to request a review? - * Where to get help -* Getting started - * Basic setup - * Git bootcamp (simplified for everyone to use) -* Code contributions - * Code setup and building (more complex stuff, delta from basic setup above) - * More git bootcamp (patches, etc) - * Lifecycle of a code pull request - * Development workflow (from devguide) - * Testing and buildbots (from devguide) - * Development tools (from devguide) - * CPython’s internals (from devguide) - * Code style guide -* Documentation contributions - * Lifecycle of a docs pull request - * (pull in Documentation sections from devguide) - * Rst/Sphinx bootcamp - * Editorial Style Guide -* Translation - * Need details -* Accessibility and user success -* Security and infrastructure - * Core Team Resources (from the devguide: I think we should reevaluate if it still makes sense to have the "How to become a core developer" section in this guide and in this particular section.) - From ea5155263ecafa788deb473b80d15b67627f9b12 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 9 Sep 2024 16:44:03 -0700 Subject: [PATCH 7/8] add discourse link to draft prolog --- conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conf.py b/conf.py index 2c93107e9a..c6fd879505 100644 --- a/conf.py +++ b/conf.py @@ -169,7 +169,7 @@ # prolog and epilogs rst_prolog = """ .. |draft| replace:: **Draft** of Python Contributor's Guide -.. |purpose| replace:: See more info about the contributor guide in Discourse. Questions? Ask the docs editorial board. +.. |purpose| replace:: See more info about the contributor guide at https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409. Questions? Ask the docs editorial board. """ # sphinx.ext.extlinks From adb60bc0fd07c4cabfe0b0497ad45d45f4fe7246 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Tue, 10 Sep 2024 09:06:07 -0700 Subject: [PATCH 8/8] Add link to EB as suggested by Guido --- conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conf.py b/conf.py index c6fd879505..21e7e9901b 100644 --- a/conf.py +++ b/conf.py @@ -169,7 +169,7 @@ # prolog and epilogs rst_prolog = """ .. |draft| replace:: **Draft** of Python Contributor's Guide -.. |purpose| replace:: See more info about the contributor guide at https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409. Questions? Ask the docs editorial board. +.. |purpose| replace:: See more info about the contributor guide at https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409. Questions? Ask the docs editorial board (https://python.github.io/editorial-board/). """ # sphinx.ext.extlinks