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.

Building the container locally

If you want more control over the environment, or to work offline, you can build the container locally. This is meant for users who have (or want to get) some experience with containers. The following instructions are a starting point for your own customizations. They assume a Unix-like environment, and Docker or Podman installed.

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, 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

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.