contrib: restructure Getting Started - Setup and Building into a Workflows section

nedbat · nedbat · commit c0171a25f76e · 2024-11-04T09:42:53.000-05:00
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.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -36,6 +36,8 @@ and are provided for development and testing purposes only.
 Install Git
 ===========
 
+.. c_install_git_start
+
 CPython is developed using `Git <https://git-scm.com>`_ 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 <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 <fork-cpython>`, :ref:`create a local
 clone of your personal fork, and configure the remotes <clone-your-fork>`.
@@ -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
 <https://github.com/python/cpython/blob/main/iOS/README.rst#debugging-test-failures>`__
 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,13 +1026,16 @@ every rule.
 ``Tools``
      Various tools that are (or have been) used to maintain Python.
 
+.. c_directory_structure_end
 
 
 .. _using-codespaces:
 
 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
@@ -41,7 +41,7 @@ Component labels
 ================
 
 These labels are mostly used to specify which :ref:`part of the codebase
-<build-directory-structure>` is affected by the issue/PR:
+<build_directory_structure>` is affected by the issue/PR:
 
 * :gh-label:`stdlib`: for standard library modules in the :cpy-file:`Lib`
   directory (written in Python).
