Important

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!

The [Plan for the Contributor’s Guide] 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.

Using GitHub Codespaces

[This is the Contribute using GitHub Codespaces section from the devguide.]

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.

Create a CPython codespace

Here are the basic steps needed to contribute a pull request 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 Code button and choose the codespaces tab and then press the green 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!

Use Codespaces locally

On the bottom left side of the codespace screen you will see a green or grey square that says 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.

Using the dev container directly

If you want more control over the environment, or to work offline, you can use the same container used in GitHub Codespaces directly. This is meant for users who have (or want to get) some experience with containers. These instructions assume a Unix-like environment with Docker or Podman installed.

Using the pre-built container image

Dev container images are available from the GitHub Container Registry (GHCR) account for the Python org.

To run the container and launch a Bash shell, run one of the following commands in a clone of the CPython repository.

docker run -it --rm --volume $PWD:/workspace --workdir /workspace ghcr.io/python/devcontainer:latest

podman run -it --rm --volume $PWD:/workspace:Z --workdir /workspace ghcr.io/python/devcontainer:latest

Note that the container has read/write access to the working directory. You may want to use a separate clone of CPython, or run make clean to remove caches and build output generated for your host OS.

Building yourself

If you prefer, you can build the container image yourself. In a clone of the cpython-devcontainers repo, build the container and name it cpython-dev:

docker build devcontainer/ --tag cpython-dev

(Substitute podman for docker if you use Podman.)

The same command will update any existing cpython-dev container. Run it again from time to time – especially if the container stops working for you.

To run the container and launch a Bash shell, run one of the following commands in a clone of the CPython repository.

docker run -it --rm --volume $PWD:/workspace --workdir /workspace cpython-dev

podman run -it --rm --volume $PWD:/workspace:Z --workdir /workspace cpython-dev

The same caveats outlined above when running from a container image from GHCR also apply here.