From be7cd9fa4b943be46714f9d6bcbd68ff552c1444 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Mon, 28 Oct 2024 11:39:52 -0400 Subject: [PATCH] contrib guide: more restructuring --- contrib/code/index.rst | 2 + .../{project => }/core-team/committing.rst | 2 +- .../{project => }/core-team/developer-log.rst | 2 +- contrib/{project => }/core-team/experts.rst | 2 +- contrib/{project => }/core-team/index.rst | 0 contrib/{project => }/core-team/join-team.rst | 2 +- .../{project => }/core-team/motivations.rst | 2 +- .../core-team/responsibilities.rst | 2 +- contrib/doc/index.rst | 2 + contrib/get-started/index.rst | 2 + contrib/index.rst | 112 ++++++++++++++++-- contrib/intro/index.rst | 19 +++ contrib/project/generative-ai.rst | 10 ++ contrib/project/index.rst | 5 +- contrib/{ => project}/outreach.rst | 0 contrib/triage/index.rst | 2 + 16 files changed, 149 insertions(+), 17 deletions(-) rename contrib/{project => }/core-team/committing.rst (78%) rename contrib/{project => }/core-team/developer-log.rst (77%) rename contrib/{project => }/core-team/experts.rst (78%) rename contrib/{project => }/core-team/index.rst (100%) rename contrib/{project => }/core-team/join-team.rst (83%) rename contrib/{project => }/core-team/motivations.rst (77%) rename contrib/{project => }/core-team/responsibilities.rst (76%) create mode 100644 contrib/project/generative-ai.rst rename contrib/{ => project}/outreach.rst (100%) diff --git a/contrib/code/index.rst b/contrib/code/index.rst index 5f1e4c0f67..7680950663 100644 --- a/contrib/code/index.rst +++ b/contrib/code/index.rst @@ -1,3 +1,5 @@ +.. _c_code: + ================== Code contributions ================== diff --git a/contrib/project/core-team/committing.rst b/contrib/core-team/committing.rst similarity index 78% rename from contrib/project/core-team/committing.rst rename to contrib/core-team/committing.rst index 569f6e27de..59cf7c1af2 100644 --- a/contrib/project/core-team/committing.rst +++ b/contrib/core-team/committing.rst @@ -8,4 +8,4 @@ [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 +.. include:: ../../core-developers/committing.rst diff --git a/contrib/project/core-team/developer-log.rst b/contrib/core-team/developer-log.rst similarity index 77% rename from contrib/project/core-team/developer-log.rst rename to contrib/core-team/developer-log.rst index 00d7803035..473cd3c6c6 100644 --- a/contrib/project/core-team/developer-log.rst +++ b/contrib/core-team/developer-log.rst @@ -8,4 +8,4 @@ [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 +.. include:: ../../core-developers/developer-log.rst diff --git a/contrib/project/core-team/experts.rst b/contrib/core-team/experts.rst similarity index 78% rename from contrib/project/core-team/experts.rst rename to contrib/core-team/experts.rst index 358fdd17fc..7f2a103cd5 100644 --- a/contrib/project/core-team/experts.rst +++ b/contrib/core-team/experts.rst @@ -8,4 +8,4 @@ [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 +.. include:: ../../core-developers/experts.rst diff --git a/contrib/project/core-team/index.rst b/contrib/core-team/index.rst similarity index 100% rename from contrib/project/core-team/index.rst rename to contrib/core-team/index.rst diff --git a/contrib/project/core-team/join-team.rst b/contrib/core-team/join-team.rst similarity index 83% rename from contrib/project/core-team/join-team.rst rename to contrib/core-team/join-team.rst index 1905c92a95..0c893ae08d 100644 --- a/contrib/project/core-team/join-team.rst +++ b/contrib/core-team/join-team.rst @@ -12,5 +12,5 @@ adjust "core developer" to "core team" where appropriate.] How to join the core team ========================= -.. include:: ../../../core-developers/become-core-developer.rst +.. include:: ../../core-developers/become-core-developer.rst :start-line: 7 diff --git a/contrib/project/core-team/motivations.rst b/contrib/core-team/motivations.rst similarity index 77% rename from contrib/project/core-team/motivations.rst rename to contrib/core-team/motivations.rst index 79af3ccfdf..c9e0281b6f 100644 --- a/contrib/project/core-team/motivations.rst +++ b/contrib/core-team/motivations.rst @@ -8,4 +8,4 @@ [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 +.. include:: ../../core-developers/motivations.rst diff --git a/contrib/project/core-team/responsibilities.rst b/contrib/core-team/responsibilities.rst similarity index 76% rename from contrib/project/core-team/responsibilities.rst rename to contrib/core-team/responsibilities.rst index ca974b35cd..a3de329561 100644 --- a/contrib/project/core-team/responsibilities.rst +++ b/contrib/core-team/responsibilities.rst @@ -8,4 +8,4 @@ [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 +.. include:: ../../core-developers/responsibilities.rst diff --git a/contrib/doc/index.rst b/contrib/doc/index.rst index 224469d2c2..dc8ec93074 100644 --- a/contrib/doc/index.rst +++ b/contrib/doc/index.rst @@ -1,3 +1,5 @@ +.. _c_docs: + =========================== Documentation contributions =========================== diff --git a/contrib/get-started/index.rst b/contrib/get-started/index.rst index 84c5afd707..70e61b1b1b 100644 --- a/contrib/get-started/index.rst +++ b/contrib/get-started/index.rst @@ -1,3 +1,5 @@ +.. _c_gettingstarted: + =============== Getting started =============== diff --git a/contrib/index.rst b/contrib/index.rst index 1c169ffbeb..f43dd3719d 100644 --- a/contrib/index.rst +++ b/contrib/index.rst @@ -1,7 +1,21 @@ +.. _c_root: + ================================== Python Contributor's Guide (draft) ================================== +.. raw:: html + + + + + .. important:: |draft| @@ -9,20 +23,94 @@ Python Contributor's Guide (draft) |purpose| -This guide is a comprehensive resource for contributing to Python. +[Open question: how to divide content between this Introduction and the +:ref:`introduction `?] + +This guide is a comprehensive resource for :ref:`contributing ` +to Python_ -- for both new and experienced contributors. It is :ref:`maintained +` by the same community that maintains Python. We welcome your +contributions to Python! + +We encourage everyone to contribute to Python. This guide should have +everything you need to get started and be productive. If you still have +questions after reviewing the material in this guide, the `Core Python +Mentorship`_ group is available to help you through the process. + +There are a number of ways to contribute including code, documentation, and +triaging issues. We've organized this guide to provide specifics based on the +type of activity you'll be engaged in. + + +Using this guide +================ + +We recommend reading this guide as needed. You can stop where you feel +comfortable and begin contributing immediately without reading and +understanding everything. If you do choose to skip around this guide, be aware +that it is written assuming preceding sections have been read so you may need +to backtrack to fill in missing concepts and terminology. -.. note:: - This is a draft of a new organization for the devguide, turning it into a - Contributor's Guide. +No matter what kind of contribution you'll be making, you should start with +these common sections: -[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.] +* :ref:`c_intro` +* :ref:`c_project` +* :ref:`c_gettingstarted` +Then choose a path based on your type of activity: + +*[The original table on the devguide home had a fourth column for Core +Developers. That made the table wider and more confusing. I don't think core +team members need a quick intro path since they will have been through the +devguide before.]* + +*[I haven't adjusted the links in the table yet other than to add a link to the +major section at the top of each column.]* + +.. list-table:: + :widths: 10 10 10 + :header-rows: 1 + + * - Triaging + - Documentation + - Code + * - + :ref:`c_triage` + + * :ref:`tracker` + * :ref:`triaging` + * :ref:`helptriage` + * :ref:`experts` + * :ref:`labels` + * :ref:`gh-faq` + * :ref:`triage-team` + - + :ref:`c_docs` + + * :ref:`docquality` + * :ref:`documenting` + * :ref:`style-guide` + * :ref:`rst-primer` + * :ref:`translating` + * :ref:`devguide` + - + :ref:`c_code` + + * :ref:`setup` + * :ref:`help` + * :ref:`pullrequest` + * :ref:`runtests` + * :ref:`fixingissues` + * :ref:`communication` + * :ref:`gitbootcamp` + * :ref:`devcycle` + +[The contents had been listed below here. It was very long, and I don't think +it was helpful. The left sidebar has the contents.] .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + :hidden: contrib-plan intro/index @@ -31,6 +119,10 @@ contribution and how to navigate the guide for your own type.] triage/index code/index doc/index + core-team/index user-success security - outreach + + +.. _Python: https://www.python.org/ +.. _Core Python Mentorship: https://www.python.org/dev/core-mentorship/ diff --git a/contrib/intro/index.rst b/contrib/intro/index.rst index 0a733adaac..aab6130bee 100644 --- a/contrib/intro/index.rst +++ b/contrib/intro/index.rst @@ -1,3 +1,5 @@ +.. _c_intro: + ============ Introduction ============ @@ -10,9 +12,26 @@ Introduction +[Open question: how to divide content between this Introduction and the +:ref:`home page `?] Welcome! +New to open source? +=================== + +Python is an open source project, with culture and techniques from the broader +open source world. You might find it helpful to read about open source in +general. A number of individuals from the Python community have contributed to +a series of excellent guides at `Open Source Guides +`_. + +Anyone will find the following guides useful: + +* `How to Contribute to Open Source `_ +* `Building Welcoming Communities `_ + + Healthy Collaboration ===================== diff --git a/contrib/project/generative-ai.rst b/contrib/project/generative-ai.rst new file mode 100644 index 0000000000..6cb5b62ffc --- /dev/null +++ b/contrib/project/generative-ai.rst @@ -0,0 +1,10 @@ +.. important:: + + |draft| + + |purpose| + + +[This is the existing :ref:`generative-ai` page from the devguide.] + +.. include:: ../../getting-started/generative-ai.rst diff --git a/contrib/project/index.rst b/contrib/project/index.rst index 082be327e8..5d26b15aab 100644 --- a/contrib/project/index.rst +++ b/contrib/project/index.rst @@ -1,3 +1,5 @@ +.. _c_project: + =================== The CPython project =================== @@ -19,7 +21,8 @@ moving parts, who is involved, how do they interact?] conduct roles - core-team/index governance + generative-ai.rst github channels + outreach diff --git a/contrib/outreach.rst b/contrib/project/outreach.rst similarity index 100% rename from contrib/outreach.rst rename to contrib/project/outreach.rst diff --git a/contrib/triage/index.rst b/contrib/triage/index.rst index 9257978a6a..0a547d9d77 100644 --- a/contrib/triage/index.rst +++ b/contrib/triage/index.rst @@ -1,3 +1,5 @@ +.. _c_triage: + =================== Issues and triaging ===================