diff --git a/contrib/core-team/index.rst b/contrib/core-team/index.rst index 281ed0f47..a89d08aff 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/get-started/index.rst b/contrib/get-started/index.rst deleted file mode 100644 index 70e61b1b1..000000000 --- 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/index.rst b/contrib/index.rst index b3ef0d992..c8318a745 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: @@ -96,6 +95,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 @@ -103,13 +106,13 @@ major section at the top of each column.]* contrib-plan intro/index project/index - get-started/index triage/index - code/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 000000000..0cebb25f7 --- /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 5d26b15aa..9d3c89b9a 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 000000000..eb97ef7c2 --- /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 000000000..18157b717 --- /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 000000000..ed56fe4e1 --- /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 new file mode 100644 index 000000000..2c6ccf2bc --- /dev/null +++ b/contrib/workflows/index.rst @@ -0,0 +1,25 @@ +.. _c_workflows: + +========= +Workflows +========= + +.. important:: + + |draft| + + |purpose| + + +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 000000000..9a511c6da --- /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 000000000..e3d738b2a --- /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 000000000..b5bca7dca --- /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 000000000..68aa80158 --- /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/documentation/markup.rst b/documentation/markup.rst index a7a9bcb76..8a6c6cd7d 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 diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 03b2777b8..29342ffc9 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``). @@ -784,9 +797,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 @@ -825,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. @@ -868,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. @@ -909,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. @@ -930,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 ================= @@ -940,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 @@ -1000,8 +1026,7 @@ every rule. ``Tools`` Various tools that are (or have been) used to maintain Python. - -.. _issue tracker: https://github.com/python/cpython/issues +.. c_directory_structure_end .. _using-codespaces: @@ -1009,6 +1034,8 @@ every rule. Contribute using GitHub Codespaces ================================== +.. c_codespaces_start + .. _codespaces-whats-codespaces: What is GitHub Codespaces? @@ -1069,5 +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/links.rst b/links.rst new file mode 100644 index 000000000..4f0eb5881 --- /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/ diff --git a/triage/labels.rst b/triage/labels.rst index c2981f666..2ab04cfab 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).