From dc0be4dbd29b6f1c7ef8281ef29cfbbbddb41177 Mon Sep 17 00:00:00 2001 From: Marlene <57748216+marlenezw@users.noreply.github.com> Date: Wed, 2 Aug 2023 18:11:57 +0200 Subject: [PATCH] Adding Codespaces Documentation (#1144) Co-authored-by: Hugo van Kemenade Co-authored-by: Pradyun Gedam Co-authored-by: Brett Cannon --- getting-started/setup-building.rst | 69 ++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 75db82ba2..60db82d47 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -655,3 +655,72 @@ every rule. .. _issue tracker: https://github.com/python/cpython/issues + + +.. _using-codespaces: + +Contribute using GitHub Codespaces +================================== + +.. _codespaces-whats-codespaces: + +What is GitHub Codespaces? +-------------------------- + +If you'd like to start contributing to CPython without needing to set up a local +developer environment, you can use +`GitHub Codespaces `_. +Codespaces is a cloud-based development environment offered by GitHub that +allows developers to write, build, test, and debug code directly within their +web browser or in Visual Studio Code (VS Code). + +To help you get started, CPython contains a +`devcontainer folder `_ +with a JSON configuration file that provides consistent and versioned codespace +configurations for all users of the project. It also contains a Dockerfile that +allows you to set up the same environment but locally in a Docker container if +you'd prefer to use that directly. + +.. _codespaces-create-a-codespace: + +Create a CPython codespace +-------------------------- + +Here are the basic steps needed to contribute a patch using Codespaces. +You first need to navigate to the +`CPython repo `_ hosted on GitHub. + +Then you will need to: + +1. Press the ``,`` key to launch the codespace setup screen for the current + branch (alternatively, click the green :guilabel:`Code` button and choose + the ``codespaces`` tab and then press the + green :guilabel:`Create codespace on main` button). +2. A screen should appear that lets you know your codespace is being set up. + (Note: Since the CPython devcontainer is provided, codespaces will use the + configuration it specifies.) +3. A `web version of VS Code `_ will open inside your web + browser, already linked up with your code and a terminal to the remote + codespace where CPython and its documentation have already been built. +4. Use the terminal with the usual Git commands to create a new branch, commit + and push your changes once you're ready! + +If you close your repository and come back later you can always resume your +codespace by navigating to the CPython repo, selecting the codespaces tab and +selecting your most recent codespaces session. You should then be able to pick +up from where you left off! + +.. _codespaces-use-locally: + +Use Codespaces Locally +---------------------- + +On the bottom left side of the codespace screen you will see a green or grey +square that says :guilabel:`Codespaces`. You can click this for additional +options. If you prefer working in a locally installed copy of VS Code you can +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