python · nedbat · Oct 16, 2024 · Sep 9, 2024 · Sep 9, 2024 · Sep 9, 2024
diff --git 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

diff --git a/conf.py b/conf.py
@@ -175,6 +175,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::
+    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
 # This config is a dictionary of external sites,
 # mapping unique short aliases to a base URL and a prefix.

diff --git a/contrib/code/index.rst b/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
diff --git a/contrib/doc/index.rst b/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
diff --git a/contrib/get-started/index.rst b/contrib/get-started/index.rst
@@ -0,0 +1,13 @@
+===============
+Getting started
+===============
+
+.. important::
+
+   |draft|
+
+   |purpose|
+
+
+* Basic setup
+* Git bootcamp (simplified for everyone to use)
diff --git a/contrib/index.rst b/contrib/index.rst
@@ -0,0 +1,29 @@
+==================================
+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.
+
+.. toctree::
+   :maxdepth: 2
+
+   intro/index
+   project/index
+   get-started/index
+   triage/index
+   code/index
+   doc/index
+   user-success
+   security
+   outreach
diff --git a/contrib/intro/index.rst b/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
+=======================
diff --git a/contrib/outreach.rst b/contrib/outreach.rst
@@ -0,0 +1,12 @@
+========
+Outreach
+========
+
+.. important::
+
+   |draft|
+
+   |purpose|
+
+
+* Sprints
diff --git a/contrib/project/channels.rst 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
@@ -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
diff --git a/contrib/project/core-team/committing.rst 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -0,0 +1,25 @@
+===================
+The CPython project
+===================
+
+.. important::
+
+   |draft|
+
+   |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
+
+.. toctree::
+   :maxdepth: 5
+
+   conduct
+   roles
+   core-team/index
+   governance
+   github
+   channels
diff --git a/contrib/project/roles.rst 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