From c6e1d869db85e60fc1d4da9bc4766bebe3719d83 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 9 Sep 2024 14:40:06 -0700 Subject: [PATCH 01/21] 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 8c19e2db3ce100156dfb974a2cd393744a919e81 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 9 Sep 2024 14:54:38 -0700 Subject: [PATCH 02/21] 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 6049c301348f45041de5c09d3e1c893e14631e12 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 9 Sep 2024 15:48:11 -0700 Subject: [PATCH 03/21] 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 aed6592c38..bd32df1d71 100644 --- a/conf.py +++ b/conf.py @@ -175,6 +175,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 6d9d0225c9fe05a3a478252d41ea3fc8269a914d Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 9 Sep 2024 15:52:12 -0700 Subject: [PATCH 04/21] 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 a3436cccb79ec750a72e692d03d98059c41d569e Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 9 Sep 2024 15:55:33 -0700 Subject: [PATCH 05/21] 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 b6b1d78b4a1109ea3311e570c55076b09cb11190 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 9 Sep 2024 15:58:01 -0700 Subject: [PATCH 06/21] 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 daad2957e4a42d2dd30ab98b96390a27492692d3 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 9 Sep 2024 16:44:03 -0700 Subject: [PATCH 07/21] 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 bd32df1d71..c877bf17c3 100644 --- a/conf.py +++ b/conf.py @@ -178,7 +178,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 1c7d54494488df16b9eb6b7d228c06e225752f2f Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Tue, 10 Sep 2024 09:06:07 -0700 Subject: [PATCH 08/21] 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 c877bf17c3..cfac2c5f47 100644 --- a/conf.py +++ b/conf.py @@ -178,7 +178,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 From da29c2b813ac7e8f1ede443d638d80a3f67310ac Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Sun, 22 Sep 2024 15:56:42 -0400 Subject: [PATCH 09/21] Remove text crossed out in the google doc --- contrib/index.rst | 10 ++++------ contrib/project.rst | 8 +++----- 2 files changed, 7 insertions(+), 11 deletions(-) diff --git a/contrib/index.rst b/contrib/index.rst index 455891b7c0..02d3cbe7ca 100644 --- a/contrib/index.rst +++ b/contrib/index.rst @@ -41,16 +41,15 @@ Proposed Contents * Standard for communication * Enforcement details * Roles - * Core teamdevelopers (from devguide) - * (SC?) (EB?) + * Core team (from devguide) * Triager * Contributors - * types of contributions, role of each contributors + * types of contributions * Governance * (SC?) (EB?) * Other WG? Typing council? C-API WG? * GitHub - * Main CPython rRepos + * Main CPython repos * Core workflow repos * Infrastructure repos * Communication channels @@ -67,7 +66,6 @@ Proposed Contents * (Reviewing) * How? Etiquette? * How to request a review? - * Where to get help * Getting started * Basic setup * Git bootcamp (simplified for everyone to use) @@ -89,6 +87,6 @@ Proposed Contents * Need details * Accessibility and user success * Security and infrastructure - * Core Team Resources (from the devguide + * Core Team Resources (from the devguide) * Outreach * Sprints diff --git a/contrib/project.rst b/contrib/project.rst index 09f545a353..bbafe844c8 100644 --- a/contrib/project.rst +++ b/contrib/project.rst @@ -14,16 +14,15 @@ The CPython project * Standard for communication * Enforcement details * Roles - * Core teamdevelopers (from devguide) - * (SC?) (EB?) + * Core team (from devguide) * Triager * Contributors - * types of contributions, role of each contributors + * types of contributions * Governance * (SC?) (EB?) * Other WG? Typing council? C-API WG? * GitHub - * Main CPython rRepos + * Main CPython repos * Core workflow repos * Infrastructure repos * Communication channels @@ -40,4 +39,3 @@ The CPython project * (Reviewing) * How? Etiquette? * How to request a review? -* Where to get help From 7903e1ce554032455d36df5ff2e8b0b29ae39986 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Mon, 30 Sep 2024 07:06:21 -0400 Subject: [PATCH 10/21] move pages into directories --- contrib/{code.rst => code/index.rst} | 0 contrib/{doc.rst => doc/index.rst} | 0 contrib/{get-started.rst => get-started/index.rst} | 0 contrib/index.rst | 10 +++++----- contrib/{intro.rst => intro/index.rst} | 0 contrib/{project.rst => project/index.rst} | 0 6 files changed, 5 insertions(+), 5 deletions(-) rename contrib/{code.rst => code/index.rst} (100%) rename contrib/{doc.rst => doc/index.rst} (100%) rename contrib/{get-started.rst => get-started/index.rst} (100%) rename contrib/{intro.rst => intro/index.rst} (100%) rename contrib/{project.rst => project/index.rst} (100%) diff --git a/contrib/code.rst b/contrib/code/index.rst similarity index 100% rename from contrib/code.rst rename to contrib/code/index.rst diff --git a/contrib/doc.rst b/contrib/doc/index.rst similarity index 100% rename from contrib/doc.rst rename to contrib/doc/index.rst diff --git a/contrib/get-started.rst b/contrib/get-started/index.rst similarity index 100% rename from contrib/get-started.rst rename to contrib/get-started/index.rst diff --git a/contrib/index.rst b/contrib/index.rst index 02d3cbe7ca..4f76fb7b09 100644 --- a/contrib/index.rst +++ b/contrib/index.rst @@ -14,11 +14,11 @@ This guide is a comprehensive resource for contributing to Python. .. toctree:: :maxdepth: 2 - intro - project - get-started - code - doc + intro/index + project/index + get-started/index + code/index + doc/index translation user-success security diff --git a/contrib/intro.rst b/contrib/intro/index.rst similarity index 100% rename from contrib/intro.rst rename to contrib/intro/index.rst diff --git a/contrib/project.rst b/contrib/project/index.rst similarity index 100% rename from contrib/project.rst rename to contrib/project/index.rst From 7d541d19cd05e09c9c2fd97b7fd33b03014f750b Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Mon, 30 Sep 2024 07:29:33 -0400 Subject: [PATCH 11/21] explain the outline on the front page --- contrib/index.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/contrib/index.rst b/contrib/index.rst index 4f76fb7b09..47e28c1838 100644 --- a/contrib/index.rst +++ b/contrib/index.rst @@ -30,6 +30,10 @@ This guide is a comprehensive resource for contributing to Python. Proposed Contents ----------------- +We are in the process of restructuring the classic "devguide" into a broader +Contribution Guide. It's being fleshed out above. This is the original +proposed outline for reference: + * 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 From fcb8086908c16a33ba691263aea29723c84b4b78 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Mon, 30 Sep 2024 21:21:11 -0400 Subject: [PATCH 12/21] more detail in the Contributor Guide top-of-page notice --- conf.py | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/conf.py b/conf.py index cfac2c5f47..e469094d76 100644 --- a/conf.py +++ b/conf.py @@ -177,8 +177,18 @@ # 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 (https://python.github.io/editorial-board/). +.. |draft| replace:: + This is part of a **Draft** of the Python Contributor's Guide. + Text in square brackets are notes about content to fill in. + We welcome help with this! + +.. |purpose| replace:: + See more info about the Contributor Guide in the discussion forum: `Refactoring the DevGuide`_. + Questions? Ask the `Docs Editorial Board`_. + +.. _Refactoring the DevGuide: https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409 +.. _Docs Editorial Board: https://python.github.io/editorial-board/ + """ # sphinx.ext.extlinks From 4eb71492ad6c5865c2b93482b892953589d4b1d5 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Mon, 30 Sep 2024 21:21:30 -0400 Subject: [PATCH 13/21] intro page headers --- contrib/intro/index.rst | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/contrib/intro/index.rst b/contrib/intro/index.rst index f0953ebbee..0a733adaac 100644 --- a/contrib/intro/index.rst +++ b/contrib/intro/index.rst @@ -9,7 +9,26 @@ Introduction |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 + + +Welcome! + +Healthy Collaboration +===================== + +[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 this Guide +======================= From d6296693ea81b875c5f5c477a48bf0a0f2a6328a Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Mon, 30 Sep 2024 21:31:32 -0400 Subject: [PATCH 14/21] put Issues and Triaging as a top-level section --- contrib/index.rst | 1 + contrib/project/index.rst | 5 ----- contrib/triage/index.rst | 11 +++++++++++ contrib/triage/issue-tracker.rst | 9 +++++++++ contrib/triage/labels.rst | 9 +++++++++ contrib/triage/triage-team.rst | 9 +++++++++ contrib/triage/triaging.rst | 9 +++++++++ 7 files changed, 48 insertions(+), 5 deletions(-) create mode 100644 contrib/triage/index.rst create mode 100644 contrib/triage/issue-tracker.rst create mode 100644 contrib/triage/labels.rst create mode 100644 contrib/triage/triage-team.rst create mode 100644 contrib/triage/triaging.rst diff --git a/contrib/index.rst b/contrib/index.rst index 47e28c1838..97e1ba0c7d 100644 --- a/contrib/index.rst +++ b/contrib/index.rst @@ -17,6 +17,7 @@ This guide is a comprehensive resource for contributing to Python. intro/index project/index get-started/index + triage/index code/index doc/index translation diff --git a/contrib/project/index.rst b/contrib/project/index.rst index bbafe844c8..4d6ca99846 100644 --- a/contrib/project/index.rst +++ b/contrib/project/index.rst @@ -31,11 +31,6 @@ The CPython project * 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? diff --git a/contrib/triage/index.rst b/contrib/triage/index.rst new file mode 100644 index 0000000000..495d93917f --- /dev/null +++ b/contrib/triage/index.rst @@ -0,0 +1,11 @@ +=================== +Issues and triaging +=================== + +.. toctree:: + :maxdepth: 5 + + issue-tracker + triaging + labels + triage-team diff --git a/contrib/triage/issue-tracker.rst b/contrib/triage/issue-tracker.rst new file mode 100644 index 0000000000..a5777bc81d --- /dev/null +++ b/contrib/triage/issue-tracker.rst @@ -0,0 +1,9 @@ +.. important:: + + |draft| + + |purpose| + +[This is the existing :ref:`issue-tracker` page from the devguide] + +.. include:: ../../triage/issue-tracker.rst diff --git a/contrib/triage/labels.rst b/contrib/triage/labels.rst new file mode 100644 index 0000000000..c364817333 --- /dev/null +++ b/contrib/triage/labels.rst @@ -0,0 +1,9 @@ +.. important:: + + |draft| + + |purpose| + +[This is the existing :ref:`labels` page from the devguide] + +.. include:: ../../triage/labels.rst diff --git a/contrib/triage/triage-team.rst b/contrib/triage/triage-team.rst new file mode 100644 index 0000000000..a9b59056a9 --- /dev/null +++ b/contrib/triage/triage-team.rst @@ -0,0 +1,9 @@ +.. important:: + + |draft| + + |purpose| + +[This is the existing :ref:`triage-team` page from the devguide] + +.. include:: ../../triage/triage-team.rst diff --git a/contrib/triage/triaging.rst b/contrib/triage/triaging.rst new file mode 100644 index 0000000000..22e1ccc657 --- /dev/null +++ b/contrib/triage/triaging.rst @@ -0,0 +1,9 @@ +.. important:: + + |draft| + + |purpose| + +[This is the existing :ref:`triaging` page from the devguide] + +.. include:: ../../triage/triaging.rst From 11530d253d4b91e2e5cb5c1f6ce2746b0e93b08b Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Mon, 30 Sep 2024 21:36:21 -0400 Subject: [PATCH 15/21] translation is part of documentation --- contrib/doc/index.rst | 3 +++ contrib/index.rst | 1 - contrib/translation.rst | 12 ------------ 3 files changed, 3 insertions(+), 13 deletions(-) delete mode 100644 contrib/translation.rst diff --git a/contrib/doc/index.rst b/contrib/doc/index.rst index 133719d6e2..e5d60e42f4 100644 --- a/contrib/doc/index.rst +++ b/contrib/doc/index.rst @@ -13,3 +13,6 @@ Documentation contributions * (pull in Documentation sections from devguide) * Rst/Sphinx bootcamp * Editorial Style Guide +* Translation + - How to add a new language + - Tools and workflow diff --git a/contrib/index.rst b/contrib/index.rst index 97e1ba0c7d..e0098248fd 100644 --- a/contrib/index.rst +++ b/contrib/index.rst @@ -20,7 +20,6 @@ This guide is a comprehensive resource for contributing to Python. triage/index code/index doc/index - translation user-success security outreach diff --git a/contrib/translation.rst b/contrib/translation.rst deleted file mode 100644 index b337fb6ff6..0000000000 --- a/contrib/translation.rst +++ /dev/null @@ -1,12 +0,0 @@ -=========== -Translation -=========== - -.. important:: - - |draft| - - |purpose| - -* How to add a new language -* Tools and workflow From d5b7038e9bb012b71faa2e6ce99a6e46a41ab9cc Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Tue, 1 Oct 2024 06:55:24 -0400 Subject: [PATCH 16/21] temp: don't let warnings fail the build --- Makefile | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 5f9e96546e..ab38ffc880 100644 --- a/Makefile +++ b/Makefile @@ -6,7 +6,12 @@ PYTHON = python3 VENVDIR = ./venv UV = uv SPHINXBUILD = $(VENVDIR)/bin/sphinx-build -SPHINXOPTS = --fail-on-warning --keep-going +# Temporary: while we are using ..include:: to show the reorganization, +# there are duplicate labels. These cause warnings, which prevent the +# build from finishing. Turn off --fail-on-warning so we can see the +# finished results. +#SPHINXOPTS = --fail-on-warning --keep-going +SPHINXOPTS = --keep-going BUILDDIR = _build BUILDER = html JOBS = auto From a48dadc62334b853525285f4dc84a0d815c8341d Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Tue, 1 Oct 2024 08:33:29 -0400 Subject: [PATCH 17/21] make more pages --- contrib/project/channels.rst | 16 ++++++++ contrib/project/conduct.rst | 15 ++++++++ contrib/project/core-team/committing.rst | 11 ++++++ contrib/project/core-team/developer-log.rst | 11 ++++++ contrib/project/core-team/experts.rst | 11 ++++++ contrib/project/core-team/index.rst | 23 ++++++++++++ contrib/project/core-team/join-team.rst | 16 ++++++++ contrib/project/core-team/motivations.rst | 11 ++++++ .../project/core-team/responsibilities.rst | 11 ++++++ contrib/project/github.rst | 15 ++++++++ contrib/project/governance.rst | 25 +++++++++++++ contrib/project/index.rst | 37 +++++++------------ contrib/project/roles.rst | 17 +++++++++ contrib/triage/index.rst | 1 + contrib/triage/reviewing.rst | 13 +++++++ core-developers/index.rst | 2 + 16 files changed, 211 insertions(+), 24 deletions(-) create mode 100644 contrib/project/channels.rst create mode 100644 contrib/project/conduct.rst create mode 100644 contrib/project/core-team/committing.rst create mode 100644 contrib/project/core-team/developer-log.rst create mode 100644 contrib/project/core-team/experts.rst create mode 100644 contrib/project/core-team/index.rst create mode 100644 contrib/project/core-team/join-team.rst create mode 100644 contrib/project/core-team/motivations.rst create mode 100644 contrib/project/core-team/responsibilities.rst create mode 100644 contrib/project/github.rst create mode 100644 contrib/project/governance.rst create mode 100644 contrib/project/roles.rst create mode 100644 contrib/triage/reviewing.rst diff --git a/contrib/project/channels.rst b/contrib/project/channels.rst new file mode 100644 index 0000000000..711dbe5879 --- /dev/null +++ b/contrib/project/channels.rst @@ -0,0 +1,16 @@ +.. important:: + + |draft| + + |purpose| + + +====================== +Communication channels +====================== + +* Repos +* Discourse +* Discord +* Mailing lists (deprioritize) +* Where to get help diff --git a/contrib/project/conduct.rst b/contrib/project/conduct.rst new file mode 100644 index 0000000000..e0dc2b5fa4 --- /dev/null +++ b/contrib/project/conduct.rst @@ -0,0 +1,15 @@ +=============== +Code of Conduct +=============== + +.. important:: + + |draft| + + |purpose| + + +[Brief summary of the code of conduct, with links to official source.] + +* Standard for communication +* Enforcement details diff --git a/contrib/project/core-team/committing.rst b/contrib/project/core-team/committing.rst new file mode 100644 index 0000000000..569f6e27de --- /dev/null +++ b/contrib/project/core-team/committing.rst @@ -0,0 +1,11 @@ +.. important:: + + |draft| + + |purpose| + + +[This is the existing core developers :ref:`committing` page from the devguide. We'll +adjust "core developer" to "core team" where appropriate.] + +.. include:: ../../../core-developers/committing.rst diff --git a/contrib/project/core-team/developer-log.rst b/contrib/project/core-team/developer-log.rst new file mode 100644 index 0000000000..00d7803035 --- /dev/null +++ b/contrib/project/core-team/developer-log.rst @@ -0,0 +1,11 @@ +.. important:: + + |draft| + + |purpose| + + +[This is the existing core developers :ref:`developer-log` page from the devguide. We'll +adjust "core developer" to "core team" where appropriate.] + +.. include:: ../../../core-developers/developer-log.rst diff --git a/contrib/project/core-team/experts.rst b/contrib/project/core-team/experts.rst new file mode 100644 index 0000000000..358fdd17fc --- /dev/null +++ b/contrib/project/core-team/experts.rst @@ -0,0 +1,11 @@ +.. important:: + + |draft| + + |purpose| + + +[This is the existing core developers :ref:`experts` page from the devguide. We'll +adjust "core developer" to "core team" where appropriate.] + +.. include:: ../../../core-developers/experts.rst diff --git a/contrib/project/core-team/index.rst b/contrib/project/core-team/index.rst new file mode 100644 index 0000000000..281ed0f479 --- /dev/null +++ b/contrib/project/core-team/index.rst @@ -0,0 +1,23 @@ +.. important:: + + |draft| + + |purpose| + + +========= +Core team +========= + +[This is mostly re-organized from the :ref:`core-dev` section of the devguide, +but with "core developer" language changed to "core team" where possible.] + +.. toctree:: + :maxdepth: 5 + + responsibilities + committing + experts + developer-log + motivations + join-team diff --git a/contrib/project/core-team/join-team.rst b/contrib/project/core-team/join-team.rst new file mode 100644 index 0000000000..1905c92a95 --- /dev/null +++ b/contrib/project/core-team/join-team.rst @@ -0,0 +1,16 @@ +.. important:: + + |draft| + + |purpose| + + +[This is the existing core developers :ref:`become-core-developer` page from the devguide with the title changed. We'll +adjust "core developer" to "core team" where appropriate.] + +========================= +How to join the core team +========================= + +.. include:: ../../../core-developers/become-core-developer.rst + :start-line: 7 diff --git a/contrib/project/core-team/motivations.rst b/contrib/project/core-team/motivations.rst new file mode 100644 index 0000000000..79af3ccfdf --- /dev/null +++ b/contrib/project/core-team/motivations.rst @@ -0,0 +1,11 @@ +.. important:: + + |draft| + + |purpose| + + +[This is the existing core developers :ref:`motivations` page from the devguide. We'll +adjust "core developer" to "core team" where appropriate.] + +.. include:: ../../../core-developers/motivations.rst diff --git a/contrib/project/core-team/responsibilities.rst b/contrib/project/core-team/responsibilities.rst new file mode 100644 index 0000000000..ca974b35cd --- /dev/null +++ b/contrib/project/core-team/responsibilities.rst @@ -0,0 +1,11 @@ +.. important:: + + |draft| + + |purpose| + + +[This is the existing core developers :ref:`responsibilities` page from the devguide. We'll +adjust "core developer" to "core team" where appropriate.] + +.. include:: ../../../core-developers/responsibilities.rst diff --git a/contrib/project/github.rst b/contrib/project/github.rst new file mode 100644 index 0000000000..fe45c6b8b1 --- /dev/null +++ b/contrib/project/github.rst @@ -0,0 +1,15 @@ +.. important:: + + |draft| + + |purpose| + +====== +GitHub +====== + +[Where are the actual artifacts?] + +* Main CPython repos +* Core workflow repos +* Infrastructure repos diff --git a/contrib/project/governance.rst b/contrib/project/governance.rst new file mode 100644 index 0000000000..a4bc66ff1b --- /dev/null +++ b/contrib/project/governance.rst @@ -0,0 +1,25 @@ +.. important:: + + |draft| + + |purpose| + + +========== +Governance +========== + +[How decisions are made, who is involved, how to participate.] + +Steering Council +================ + +Documentation Editorial Board +============================= + +Typing Council +============== + + +Others? +======= diff --git a/contrib/project/index.rst b/contrib/project/index.rst index 4d6ca99846..082be327e8 100644 --- a/contrib/project/index.rst +++ b/contrib/project/index.rst @@ -9,28 +9,17 @@ The CPython project |purpose| +[Give the reader an understanding of the project as a whole. What are the +moving parts, who is involved, how do they interact?] + * Structure -* CoC - * Standard for communication - * Enforcement details -* Roles - * Core team (from devguide) - * Triager - * Contributors - * types of contributions -* Governance - * (SC?) (EB?) - * Other WG? Typing council? C-API WG? -* GitHub - * Main CPython repos - * Core workflow repos - * Infrastructure repos -* Communication channels - * Repos - * Discourse - * Discord - * Mailing lists (deprioritize) - * Where to get help -* (Reviewing) - * How? Etiquette? - * How to request a review? + +.. toctree:: + :maxdepth: 5 + + conduct + roles + core-team/index + governance + github + channels diff --git a/contrib/project/roles.rst b/contrib/project/roles.rst new file mode 100644 index 0000000000..8336fe4651 --- /dev/null +++ b/contrib/project/roles.rst @@ -0,0 +1,17 @@ +===== +Roles +===== + +.. important:: + + |draft| + + |purpose| + + +[Quick overview of the roles people play. Core team has its own section.] + +* Core team +* Triager +* Contributors + * types of contributions diff --git a/contrib/triage/index.rst b/contrib/triage/index.rst index 495d93917f..9257978a6a 100644 --- a/contrib/triage/index.rst +++ b/contrib/triage/index.rst @@ -8,4 +8,5 @@ Issues and triaging issue-tracker triaging labels + reviewing triage-team diff --git a/contrib/triage/reviewing.rst b/contrib/triage/reviewing.rst new file mode 100644 index 0000000000..060f6b78dd --- /dev/null +++ b/contrib/triage/reviewing.rst @@ -0,0 +1,13 @@ +.. important:: + + |draft| + + |purpose| + + +========= +Reviewing +========= + +* How? Etiquette? +* How to request a review? diff --git a/core-developers/index.rst b/core-developers/index.rst index 2b3ac7b799..8555943a07 100644 --- a/core-developers/index.rst +++ b/core-developers/index.rst @@ -1,3 +1,5 @@ +.. _core-dev: + =============== Core developers =============== From e8b74ade1d1c3284ad18c705f5f34b104f0667c6 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Tue, 1 Oct 2024 08:39:20 -0400 Subject: [PATCH 18/21] explain the internal structure for reviewers --- conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/conf.py b/conf.py index e469094d76..40b3e1adda 100644 --- a/conf.py +++ b/conf.py @@ -180,6 +180,10 @@ .. |draft| replace:: This is part of a **Draft** of the Python Contributor's Guide. Text in square brackets are notes about content to fill in. + Currently, the devguide and this new Contributor's Guide co-exist in the + repo. We are using Sphinx include directives to demonstrate the re-organization. + The final Contributor's Guide will replace the devguide with content in only one + place. We welcome help with this! .. |purpose| replace:: From 66f4bd5f6877b333e4caa03afc2d9ad729a2ec04 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Sat, 12 Oct 2024 08:04:11 -0400 Subject: [PATCH 19/21] add 'how to report' for conduct --- contrib/project/conduct.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/contrib/project/conduct.rst b/contrib/project/conduct.rst index e0dc2b5fa4..37fe3bbfa7 100644 --- a/contrib/project/conduct.rst +++ b/contrib/project/conduct.rst @@ -12,4 +12,5 @@ Code of Conduct [Brief summary of the code of conduct, with links to official source.] * Standard for communication +* How to report * Enforcement details From 7cb109c25f4ef9c0f3fdf7d4183532833e413e9a Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Sat, 12 Oct 2024 08:05:15 -0400 Subject: [PATCH 20/21] remove the outline since it's now being fleshed out --- contrib/index.rst | 75 +++-------------------------------------------- 1 file changed, 4 insertions(+), 71 deletions(-) diff --git a/contrib/index.rst b/contrib/index.rst index e0098248fd..43dc52d746 100644 --- a/contrib/index.rst +++ b/contrib/index.rst @@ -11,6 +11,10 @@ Python Contributor's Guide (draft) This guide is a comprehensive resource for contributing to Python. +.. note:: + This is a draft of a new organization for the devguide, turning it into a + Contributor's Guide. + .. toctree:: :maxdepth: 2 @@ -23,74 +27,3 @@ This guide is a comprehensive resource for contributing to Python. user-success security outreach - - -.. _proposed_contents: - -Proposed Contents ------------------ - -We are in the process of restructuring the classic "devguide" into a broader -Contribution Guide. It's being fleshed out above. This is the original -proposed outline for reference: - -* 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 team (from devguide) - * Triager - * Contributors - * types of contributions - * Governance - * (SC?) (EB?) - * Other WG? Typing council? C-API WG? - * GitHub - * Main CPython repos - * 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? -* 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) -* Outreach - * Sprints From ae48c29a8da7f50c754a465b01da4301175de0ca Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Mon, 14 Oct 2024 17:55:17 -0400 Subject: [PATCH 21/21] Add a 'plan for the contributor guide' page --- conf.py | 6 ++--- contrib/contrib-plan.rst | 47 ++++++++++++++++++++++++++++++++++++++++ contrib/index.rst | 7 ++++++ 3 files changed, 57 insertions(+), 3 deletions(-) create mode 100644 contrib/contrib-plan.rst diff --git a/conf.py b/conf.py index 40b3e1adda..1535ebfa00 100644 --- a/conf.py +++ b/conf.py @@ -187,11 +187,11 @@ We welcome help with this! .. |purpose| replace:: - See more info about the Contributor Guide in the discussion forum: `Refactoring the DevGuide`_. - Questions? Ask the `Docs Editorial Board`_. + The :ref:`contrib-plan` page has more details about the current state of this draft + and **how you can help**. See more info about the Contributor Guide in the + discussion forum: `Refactoring the DevGuide`_. .. _Refactoring the DevGuide: https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409 -.. _Docs Editorial Board: https://python.github.io/editorial-board/ """ diff --git a/contrib/contrib-plan.rst b/contrib/contrib-plan.rst new file mode 100644 index 0000000000..be35c1a8db --- /dev/null +++ b/contrib/contrib-plan.rst @@ -0,0 +1,47 @@ +.. _contrib-plan: + +================================ +Plan for the Contributor's Guide +================================ + +.. important:: + + |draft| + + |purpose| + +We are in the process of updating and refactoring the devguide to be a +Contributor's Guide. It will highlight the different kinds of contribution +possible, and how to succeed at each kind. + +Currently, the Contibutor's Guide is a draft in this new last section of the +devguide. We welcome feedback, but please understand that some of the current +content is moving or skeletal. + +Repo structure +============== + +While the reorganization is happening, we are keeping the old devguide as it +is. The new Contributor's Guide is represented in this last section, but will +eventually be the only content in the guide. To avoid copying content, we're +using Sphinx include directives to display existing devguide content in its new +Contributor's Guide location. That is not how the eventual Guide will be +built. Once we are ready to make the Contributor's Guide real, we will +rearrange content into its new location. + +How to help +=========== + +To help, you can: + +- `Write an issue`_ detailing a change you'd like to see here. +- `Make a pull request`_ in this repo to add content. +- Join us in the `Python Docs Discord`_ to collaborate with other docs-minded + community members. +- Get in touch with the `Docs Editorial Board`_ to discuss larger documentation + concerns. + +.. _Write an issue: https://github.com/python/devguide/issues +.. _Make a pull request: https://github.com/python/devguide/pulls +.. _Python Docs Discord: https://discord.gg/NeGgyhUZ +.. _Docs Editorial Board: https://python.github.io/editorial-board/ diff --git a/contrib/index.rst b/contrib/index.rst index 43dc52d746..1c169ffbeb 100644 --- a/contrib/index.rst +++ b/contrib/index.rst @@ -15,9 +15,16 @@ This guide is a comprehensive resource for contributing to Python. This is a draft of a new organization for the devguide, turning it into a Contributor's Guide. +[Much of the devguide home page will be here. The Quick Start will be updated +to distinguish code vs documentation contributions, and moved to those +sections. Other changes will be made to explain the different types of +contribution and how to navigate the guide for your own type.] + + .. toctree:: :maxdepth: 2 + contrib-plan intro/index project/index get-started/index