From c2fc4a10af65b33c1f44e5c45b7f9204ba8cc2c2 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Mon, 4 Nov 2024 07:36:43 -0500 Subject: [PATCH 1/6] todo: why duplicate toctree docs here? --- documentation/markup.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/documentation/markup.rst b/documentation/markup.rst index a7a9bcb767..8a6c6cd7d2 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -1219,6 +1219,9 @@ units as well as normal text: Table-of-contents markup ------------------------ +.. TODO: This is a copy of the Sphinx description of the toctree directive. + Why duplicate it here? + Since reST does not have facilities to interconnect several documents, or split documents into multiple output files, Sphinx uses a custom directive to add relations between the single files the documentation is made of, as well as From 88c2f24c9f187f444d6e169e29fe30c54079b733 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Mon, 4 Nov 2024 09:49:22 -0500 Subject: [PATCH 2/6] general re-organization --- contrib/core-team/index.rst | 2 ++ contrib/index.rst | 6 +++++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/contrib/core-team/index.rst b/contrib/core-team/index.rst index 281ed0f479..a89d08affc 100644 --- a/contrib/core-team/index.rst +++ b/contrib/core-team/index.rst @@ -5,6 +5,8 @@ |purpose| +.. _c_coreteam: + ========= Core team ========= diff --git a/contrib/index.rst b/contrib/index.rst index b3ef0d992a..19030e6d58 100644 --- a/contrib/index.rst +++ b/contrib/index.rst @@ -96,6 +96,10 @@ major section at the top of each column.]* * :ref:`gitbootcamp` * :ref:`devcycle` +Core team members will find guidance in the :ref:`c_coreteam` section. + +Contents +======== .. toctree:: :maxdepth: 3 @@ -105,8 +109,8 @@ major section at the top of each column.]* project/index get-started/index triage/index - code/index doc/index + code/index core-team/index user-success security From ab7988c258645c20c3bc2d5589fa793de6bb89bb Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Mon, 4 Nov 2024 09:49:31 -0500 Subject: [PATCH 3/6] contrib: replace Get Started with Workflows --- contrib/get-started/index.rst | 15 --------------- contrib/workflows/index.rst | 15 +++++++++++++++ 2 files changed, 15 insertions(+), 15 deletions(-) delete mode 100644 contrib/get-started/index.rst create mode 100644 contrib/workflows/index.rst diff --git a/contrib/get-started/index.rst b/contrib/get-started/index.rst deleted file mode 100644 index 70e61b1b1b..0000000000 --- a/contrib/get-started/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _c_gettingstarted: - -=============== -Getting started -=============== - -.. important:: - - |draft| - - |purpose| - - -* Basic setup -* Git bootcamp (simplified for everyone to use) diff --git a/contrib/workflows/index.rst b/contrib/workflows/index.rst new file mode 100644 index 0000000000..762a80e20b --- /dev/null +++ b/contrib/workflows/index.rst @@ -0,0 +1,15 @@ +.. _c_workflows: + +========= +Workflows +========= + +.. important:: + + |draft| + + |purpose| + + +This section contains details of workflows needed for all kinds of +contribution. From be05b4f0bfb93fdf8d47e3bfca14fc3871625679 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Mon, 4 Nov 2024 09:49:34 -0500 Subject: [PATCH 4/6] a central links file This makes it easier to move content around without worrying about where the links are defined. It will also be easier to have canonical links that can be used from multiple places in the guide. --- getting-started/setup-building.rst | 8 +++----- links.rst | 6 ++++++ 2 files changed, 9 insertions(+), 5 deletions(-) create mode 100644 links.rst diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 03b2777b8e..8f43a73ae5 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -784,9 +784,6 @@ some of CPython's modules (for example, ``zlib``). to the `macOS README `_. - .. _clang: https://clang.llvm.org/ - .. _ccache: https://ccache.dev/ - .. note:: While you need a C compiler to build CPython, you don't need any knowledge of the C language to contribute! Vast areas of CPython are written completely in Python: as of this writing, CPython contains slightly @@ -1001,8 +998,6 @@ every rule. Various tools that are (or have been) used to maintain Python. -.. _issue tracker: https://github.com/python/cpython/issues - .. _using-codespaces: @@ -1071,3 +1066,6 @@ power may be a much higher spec than your local machine which can be helpful. .. TODO: add docker instructions + + +.. include:: ../links.rst diff --git a/links.rst b/links.rst new file mode 100644 index 0000000000..4f0eb58814 --- /dev/null +++ b/links.rst @@ -0,0 +1,6 @@ +.. Links for use anywhere. Include this file to use them. + +.. _issue tracker: https://github.com/python/cpython/issues + +.. _clang: https://clang.llvm.org/ +.. _ccache: https://ccache.dev/ From e38851cddf5b84b9052731afcd3b431666509ce0 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Mon, 4 Nov 2024 09:42:53 -0500 Subject: [PATCH 5/6] contrib: restructure Getting Started - Setup and Building into a Workflows section The Getting Started section has a lot of technical detail. I thought it would be better moved to the end, and referenced from the contribution paths earlier in the guide. I haven't updated the paths yet. Also: - I added a central links.rst that can be included anywhere. - I omitted the "Editors and tools" section. It doesn't provide any useful information. - Perhaps the Workflows section could be further categorized. - The `c_blah_start` and `c_blah_end` comments are only for the temporary inclusions being used to demonstrate the new organization. --- contrib/index.rst | 3 +- contrib/project/directory-structure.rst | 17 ++++++++ contrib/project/index.rst | 1 + contrib/workflows/codespaces.rst | 17 ++++++++ contrib/workflows/compile.rst | 22 ++++++++++ contrib/workflows/get-source.rst | 19 +++++++++ contrib/workflows/index.rst | 10 +++++ contrib/workflows/install-dependencies.rst | 17 ++++++++ contrib/workflows/install-git.rst | 17 ++++++++ contrib/workflows/regenerate.rst | 28 +++++++++++++ contrib/workflows/troubleshooting.rst | 17 ++++++++ getting-started/setup-building.rst | 48 ++++++++++++++++++---- triage/labels.rst | 2 +- 13 files changed, 208 insertions(+), 10 deletions(-) create mode 100644 contrib/project/directory-structure.rst create mode 100644 contrib/workflows/codespaces.rst create mode 100644 contrib/workflows/compile.rst create mode 100644 contrib/workflows/get-source.rst create mode 100644 contrib/workflows/install-dependencies.rst create mode 100644 contrib/workflows/install-git.rst create mode 100644 contrib/workflows/regenerate.rst create mode 100644 contrib/workflows/troubleshooting.rst diff --git a/contrib/index.rst b/contrib/index.rst index 19030e6d58..c8318a7458 100644 --- a/contrib/index.rst +++ b/contrib/index.rst @@ -52,7 +52,6 @@ these common sections: * :ref:`c_intro` * :ref:`c_project` -* :ref:`c_gettingstarted` Then choose a path based on your type of activity: @@ -107,13 +106,13 @@ Contents contrib-plan intro/index project/index - get-started/index triage/index doc/index code/index core-team/index user-success security + workflows/index .. _Python: https://www.python.org/ diff --git a/contrib/project/directory-structure.rst b/contrib/project/directory-structure.rst new file mode 100644 index 0000000000..0cebb25f7f --- /dev/null +++ b/contrib/project/directory-structure.rst @@ -0,0 +1,17 @@ +.. important:: + + |draft| + + |purpose| + +.. _c_directory_structure: + +=================== +Directory structure +=================== + +[This is the :ref:`build_directory_structure` section from the devguide.] + +.. include:: ../../getting-started/setup-building.rst + :start-after: c_directory_structure_start + :end-before: c_directory_structure_end diff --git a/contrib/project/index.rst b/contrib/project/index.rst index 5d26b15aab..9d3c89b9a9 100644 --- a/contrib/project/index.rst +++ b/contrib/project/index.rst @@ -24,5 +24,6 @@ moving parts, who is involved, how do they interact?] governance generative-ai.rst github + directory-structure.rst channels outreach diff --git a/contrib/workflows/codespaces.rst b/contrib/workflows/codespaces.rst new file mode 100644 index 0000000000..eb97ef7c2a --- /dev/null +++ b/contrib/workflows/codespaces.rst @@ -0,0 +1,17 @@ +.. important:: + + |draft| + + |purpose| + +.. _c_using_codespaces: + +======================= +Using GitHub Codespaces +======================= + +[This is the :ref:`using-codespaces` section from the devguide.] + +.. include:: ../../getting-started/setup-building.rst + :start-after: c_codespaces_start + :end-before: c_codespaces_end diff --git a/contrib/workflows/compile.rst b/contrib/workflows/compile.rst new file mode 100644 index 0000000000..18157b717e --- /dev/null +++ b/contrib/workflows/compile.rst @@ -0,0 +1,22 @@ +.. important:: + + |draft| + + |purpose| + +.. _c_compiling: + +================= +Compile and build +================= + +.. note:: + [This is the :ref:`compiling` section from the devguide. I think this page + is too long and could be split by build target, but we can leave that for a + later time.] + +.. include:: ../../getting-started/setup-building.rst + :start-after: c_compile_and_build_start + :end-before: c_compile_and_build_end + +.. include:: ../../links.rst diff --git a/contrib/workflows/get-source.rst b/contrib/workflows/get-source.rst new file mode 100644 index 0000000000..ed56fe4e12 --- /dev/null +++ b/contrib/workflows/get-source.rst @@ -0,0 +1,19 @@ +.. important:: + + |draft| + + |purpose| + +.. _c_checkout: + +=================== +Get the source code +=================== + +.. note:: + [This is the :ref:`checkout` section from the devguide. We might need to edit + it to clarify that some steps are only needed for code contribution.] + +.. include:: ../../getting-started/setup-building.rst + :start-after: c_get_source_code_start + :end-before: c_get_source_code_end diff --git a/contrib/workflows/index.rst b/contrib/workflows/index.rst index 762a80e20b..2c6ccf2bc9 100644 --- a/contrib/workflows/index.rst +++ b/contrib/workflows/index.rst @@ -13,3 +13,13 @@ Workflows This section contains details of workflows needed for all kinds of contribution. + +.. toctree:: + + install-git.rst + get-source.rst + install-dependencies.rst + compile.rst + regenerate.rst + troubleshooting.rst + codespaces.rst diff --git a/contrib/workflows/install-dependencies.rst b/contrib/workflows/install-dependencies.rst new file mode 100644 index 0000000000..9a511c6da2 --- /dev/null +++ b/contrib/workflows/install-dependencies.rst @@ -0,0 +1,17 @@ +.. important:: + + |draft| + + |purpose| + +.. _c_build-dependencies: + +==================== +Install Dependencies +==================== + +[This is the :ref:`build-dependencies` section from the devguide.] + +.. include:: ../../getting-started/setup-building.rst + :start-after: c_install_dependencies_start + :end-before: c_install_dependencies_end diff --git a/contrib/workflows/install-git.rst b/contrib/workflows/install-git.rst new file mode 100644 index 0000000000..e3d738b2ac --- /dev/null +++ b/contrib/workflows/install-git.rst @@ -0,0 +1,17 @@ +.. important:: + + |draft| + + |purpose| + +.. _c_vcsetup: + +=========== +Install Git +=========== + +[This is the :ref:`vcsetup` section from the devguide.] + +.. include:: ../../getting-started/setup-building.rst + :start-after: c_install_git_start + :end-before: c_install_git_end diff --git a/contrib/workflows/regenerate.rst b/contrib/workflows/regenerate.rst new file mode 100644 index 0000000000..b5bca7dca7 --- /dev/null +++ b/contrib/workflows/regenerate.rst @@ -0,0 +1,28 @@ +.. important:: + + |draft| + + |purpose| + +.. _c_regenerating: + +=============================== +Regenerating auto-created files +=============================== + +.. note:: + [These are two similar sections from the is the :ref:`setup-building` section from the devguide.] + +Regenerate ``configure`` +======================== + +.. include:: ../../getting-started/setup-building.rst + :start-after: c_regenerate_configure_start + :end-before: c_regenerate_configure_end + +Regenerate the ABI dump +======================= + +.. include:: ../../getting-started/setup-building.rst + :start-after: c_regenerate_abi_start + :end-before: c_regenerate_abi_end diff --git a/contrib/workflows/troubleshooting.rst b/contrib/workflows/troubleshooting.rst new file mode 100644 index 0000000000..68aa801584 --- /dev/null +++ b/contrib/workflows/troubleshooting.rst @@ -0,0 +1,17 @@ +.. important:: + + |draft| + + |purpose| + +.. _c_build_troubleshooting: + +=========== +Install Git +=========== + +[This is the :ref:`build_troubleshooting` section from the devguide.] + +.. include:: ../../getting-started/setup-building.rst + :start-after: c_build_troubleshooting_start + :end-before: c_build_troubleshooting_end diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 8f43a73ae5..29342ffc96 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -36,6 +36,8 @@ and are provided for development and testing purposes only. Install Git =========== +.. c_install_git_start + CPython is developed using `Git `_ for version control. The Git command line program is named ``git``; this is also used to refer to Git itself. Git is easily available for all common operating systems. @@ -58,12 +60,15 @@ itself. Git is easily available for all common operating systems. ``git push``, or ``git fetch``. On Windows, you should also :ref:`enable autocrlf `. +.. c_install_git_end .. _checkout: Get the source code =================== +.. c_get_source_code_start + The CPython repo is hosted on GitHub. To get a copy of the source code you should :ref:`fork the Python repository on GitHub `, :ref:`create a local clone of your personal fork, and configure the remotes `. @@ -143,11 +148,15 @@ To make sure your code is linted correctly, we recommend setting up Now pre-commit will run automatically on ``git commit``. +.. c_get_source_code_end + .. _compiling: Compile and build ================= +.. c_compile_and_build_start + CPython provides several compilation flags which help with debugging various things. While all of the known flags can be found in the ``Misc/SpecialBuilds.txt`` file, the most critical one is the ``Py_DEBUG`` flag @@ -606,6 +615,8 @@ single test, or a subset of tests. See the `iOS README `__ for details. +.. c_compile_and_build_end + .. _build-dependencies: .. _deps-on-linux: .. _macOS and OS X: @@ -614,6 +625,8 @@ for details. Install dependencies ==================== +.. c_install_dependencies_start + This section explains how to install libraries which are needed to compile some of CPython's modules (for example, ``zlib``). @@ -822,11 +835,15 @@ some of CPython's modules (for example, ``zlib``). CPython. If you use the pre-compiled binaries, you should unpack each tarball into a separate folder, and use that folder as the configuration target. +.. c_install_dependencies_end + .. _regenerate_configure: Regenerate ``configure`` ======================== +.. c_regenerate_configure_start + If a change is made to Python which relies on some POSIX system-specific functionality (such as using a new system call), it is necessary to update the :cpy-file:`configure` script to test for availability of the functionality. @@ -865,19 +882,21 @@ and make sure the :file:`pkg.m4` macro file located in the appropriate :program:`autoreconf` runs :program:`autoconf` and a number of other tools repeatedly as appropriate. -.. _build_troubleshooting: +.. c_regenerate_configure_end Regenerate the ABI dump ======================= +.. c_regenerate_abi_start + Maintenance branches (not ``main``) have a special file located in -``Doc/data/pythonX.Y.abi`` that allows us to know if a given Pull Request +``Doc/data/pythonX.Y.abi`` that allows us to know if a given pull request affects the public ABI. This file is used by the GitHub CI in a check -called ``Check if the ABI has changed`` that will fail if a given Pull Request +called ``Check if the ABI has changed`` that will fail if a given pull request has changes to the ABI and the ABI file is not updated. -This check acts as a fail-safe and **doesn't necessarily mean that the Pull -Request cannot be merged**. When this check fails you should add the relevant +This check acts as a fail-safe and **doesn't necessarily mean that the pull +request cannot be merged**. When this check fails you should add the relevant release manager to the PR so that they are aware of the change and they can validate if the change can be made or not. @@ -906,9 +925,15 @@ Note that the ``ubuntu`` version used to execute the script matters and **must** match the version used by the CI to check the ABI. See the ``.github/workflows/build.yml`` file for more information. +.. c_regenerate_abi_end + +.. _build_troubleshooting: + Troubleshoot the build ====================== +.. c_build_troubleshooting_start + This section lists some of the common problems that may arise during the compilation of Python, with proposed solutions. @@ -927,6 +952,8 @@ To overcome this problem, auto-generated files are also checked into the Git repository. So if you don't touch the auto-generation scripts, there's no real need to auto-generate anything. +.. c_build_troubleshooting_end + Editors and tools ================= @@ -937,11 +964,13 @@ support. For editors and tools which the core developers have felt some special comment is needed for coding *in* Python, see :ref:`resources`. -.. _build-directory-structure: +.. _build_directory_structure: Directory structure =================== +.. c_directory_structure_start + There are several top-level directories in the CPython source tree. Knowing what each one is meant to hold will help you find where a certain piece of functionality is implemented. Do realize, though, there are always exceptions to @@ -997,6 +1026,7 @@ every rule. ``Tools`` Various tools that are (or have been) used to maintain Python. +.. c_directory_structure_end .. _using-codespaces: @@ -1004,6 +1034,8 @@ every rule. Contribute using GitHub Codespaces ================================== +.. c_codespaces_start + .. _codespaces-whats-codespaces: What is GitHub Codespaces? @@ -1064,8 +1096,10 @@ select the option ``Open in VS Code``. You will still be working on the remote codespace instance, thus using the remote instance's compute power. The compute power may be a much higher spec than your local machine which can be helpful. - .. TODO: add docker instructions +.. c_codespaces_end + + .. include:: ../links.rst diff --git a/triage/labels.rst b/triage/labels.rst index c2981f666d..2ab04cfab1 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -41,7 +41,7 @@ Component labels ================ These labels are mostly used to specify which :ref:`part of the codebase -` is affected by the issue/PR: +` is affected by the issue/PR: * :gh-label:`stdlib`: for standard library modules in the :cpy-file:`Lib` directory (written in Python). From 3fed878c3320a1a949fee2f659abfbf7d1726982 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Mon, 11 Nov 2024 17:58:02 -0500 Subject: [PATCH 6/6] re-order the columns --- contrib/index.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/contrib/index.rst b/contrib/index.rst index c8318a7458..f9b54bc56a 100644 --- a/contrib/index.rst +++ b/contrib/index.rst @@ -67,18 +67,10 @@ major section at the top of each column.]* :widths: 10 10 10 :header-rows: 1 - * - :ref:`Triaging ` - - :ref:`Documentation ` + * - :ref:`Documentation ` - :ref:`Code ` + - :ref:`Triaging ` * - - * :ref:`tracker` - * :ref:`triaging` - * :ref:`helptriage` - * :ref:`experts` - * :ref:`labels` - * :ref:`gh-faq` - * :ref:`triage-team` - - * :ref:`docquality` * :ref:`documenting` * :ref:`style-guide` @@ -94,6 +86,14 @@ major section at the top of each column.]* * :ref:`communication` * :ref:`gitbootcamp` * :ref:`devcycle` + - + * :ref:`tracker` + * :ref:`triaging` + * :ref:`helptriage` + * :ref:`experts` + * :ref:`labels` + * :ref:`gh-faq` + * :ref:`triage-team` Core team members will find guidance in the :ref:`c_coreteam` section.