Flesh out the Contributor's Guide (#1426)

A start on the new organization turning the devguide into a Contributor's Guide.

Co-authored-by: Carol Willing <[email protected]>

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

conf.py

@@ -171,6 +171,26 @@
 # sphinx-notfound-page
 notfound_urls_prefix = "/"
 
+# prolog and epilogs
+rst_prolog = """
+.. |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::
+    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
+
+"""
+
 # sphinx.ext.extlinks
 # This config is a dictionary of external sites,
 # mapping unique short aliases to a base URL and a prefix.

contrib/code/index.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

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/

contrib/doc/index.rst

@@ -0,0 +1,18 @@
+===========================
+Documentation contributions
+===========================
+
+.. important::
+
+   |draft|
+
+   |purpose|
+
+
+* Lifecycle of a docs pull request
+* (pull in Documentation sections from devguide)
+* Rst/Sphinx bootcamp
+* Editorial Style Guide
+* Translation
+   - How to add a new language
+   - Tools and workflow

contrib/get-started/index.rst

@@ -0,0 +1,13 @@
+===============
+Getting started
+===============
+
+.. important::
+
+   |draft|
+
+   |purpose|
+
+
+* Basic setup
+* Git bootcamp (simplified for everyone to use)

contrib/index.rst

@@ -0,0 +1,36 @@
+==================================
+Python Contributor's Guide (draft)
+==================================
+
+.. important::
+
+   |draft|
+
+   |purpose|
+
+
+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.
+
+[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
+   triage/index
+   code/index
+   doc/index
+   user-success
+   security
+   outreach

contrib/intro/index.rst

@@ -0,0 +1,34 @@
+============
+Introduction
+============
+
+.. important::
+
+   |draft|
+
+   |purpose|
+
+
+
+
+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
+=======================

contrib/outreach.rst

@@ -0,0 +1,12 @@
+========
+Outreach
+========
+
+.. important::
+
+   |draft|
+
+   |purpose|
+
+
+* Sprints

contrib/project/channels.rst

@@ -0,0 +1,16 @@
+.. important::
+
+   |draft|
+
+   |purpose|
+
+
+======================
+Communication channels
+======================
+
+* Repos
+* Discourse
+* Discord
+* Mailing lists (deprioritize)
+* Where to get help

contrib/project/conduct.rst

@@ -0,0 +1,16 @@
+===============
+Code of Conduct
+===============
+
+.. important::
+
+   |draft|
+
+   |purpose|
+
+
+[Brief summary of the code of conduct, with links to official source.]
+
+* Standard for communication
+* How to report
+* Enforcement details

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

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

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

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

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

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

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

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