From 293785f2deb687c7c024852f92621db002ac282e Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Wed, 16 Oct 2024 06:35:14 -0400 Subject: [PATCH] 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 --- Makefile | 7 ++- conf.py | 20 ++++++++ contrib/code/index.rst | 18 +++++++ contrib/contrib-plan.rst | 47 +++++++++++++++++++ contrib/doc/index.rst | 18 +++++++ contrib/get-started/index.rst | 13 +++++ contrib/index.rst | 36 ++++++++++++++ contrib/intro/index.rst | 34 ++++++++++++++ contrib/outreach.rst | 12 +++++ contrib/project/channels.rst | 16 +++++++ contrib/project/conduct.rst | 16 +++++++ 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 | 25 ++++++++++ contrib/project/roles.rst | 17 +++++++ contrib/security.rst | 13 +++++ contrib/triage/index.rst | 12 +++++ contrib/triage/issue-tracker.rst | 9 ++++ contrib/triage/labels.rst | 9 ++++ contrib/triage/reviewing.rst | 13 +++++ contrib/triage/triage-team.rst | 9 ++++ contrib/triage/triaging.rst | 9 ++++ contrib/user-success.rst | 14 ++++++ core-developers/index.rst | 2 + index.rst | 1 + 32 files changed, 503 insertions(+), 1 deletion(-) create mode 100644 contrib/code/index.rst create mode 100644 contrib/contrib-plan.rst create mode 100644 contrib/doc/index.rst create mode 100644 contrib/get-started/index.rst create mode 100644 contrib/index.rst create mode 100644 contrib/intro/index.rst create mode 100644 contrib/outreach.rst 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/index.rst create mode 100644 contrib/project/roles.rst create mode 100644 contrib/security.rst 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/reviewing.rst create mode 100644 contrib/triage/triage-team.rst create mode 100644 contrib/triage/triaging.rst create mode 100644 contrib/user-success.rst 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 diff --git a/conf.py b/conf.py index 842bf1b0c4..74137e8b54 100644 --- a/conf.py +++ b/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. diff --git a/contrib/code/index.rst b/contrib/code/index.rst new file mode 100644 index 0000000000..6c23c3a87a --- /dev/null +++ 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/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/doc/index.rst b/contrib/doc/index.rst new file mode 100644 index 0000000000..e5d60e42f4 --- /dev/null +++ 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 new file mode 100644 index 0000000000..84c5afd707 --- /dev/null +++ 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 new file mode 100644 index 0000000000..1c169ffbeb --- /dev/null +++ b/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 diff --git a/contrib/intro/index.rst b/contrib/intro/index.rst new file mode 100644 index 0000000000..0a733adaac --- /dev/null +++ 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 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/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..37fe3bbfa7 --- /dev/null +++ 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 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 new file mode 100644 index 0000000000..082be327e8 --- /dev/null +++ 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 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/security.rst b/contrib/security.rst new file mode 100644 index 0000000000..db40b4a167 --- /dev/null +++ b/contrib/security.rst @@ -0,0 +1,13 @@ +========================================= +Security and infrastructure contributions +========================================= + +.. important:: + + |draft| + + |purpose| + +* Security +* Infrastructure +* Core workflow diff --git a/contrib/triage/index.rst b/contrib/triage/index.rst new file mode 100644 index 0000000000..9257978a6a --- /dev/null +++ b/contrib/triage/index.rst @@ -0,0 +1,12 @@ +=================== +Issues and triaging +=================== + +.. toctree:: + :maxdepth: 5 + + issue-tracker + triaging + labels + reviewing + 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/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/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 diff --git a/contrib/user-success.rst b/contrib/user-success.rst new file mode 100644 index 0000000000..2a9ef5d4e5 --- /dev/null +++ b/contrib/user-success.rst @@ -0,0 +1,14 @@ +======================================= +Accessibility, design, and user success +======================================= + +.. important:: + + |draft| + + |purpose| + + +* Accessibility +* Design +* User success 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 =============== 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