Skip to content

Commit

Permalink
Update docs site for version 2.25.0.dev2 (#302)
Browse files Browse the repository at this point in the history
  • Loading branch information
WorkerPants authored Dec 18, 2024
1 parent 76a04da commit a6340b7
Show file tree
Hide file tree
Showing 25 changed files with 237 additions and 95 deletions.
44 changes: 44 additions & 0 deletions docs/docs/contributions/development/setting-up-pants.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -116,3 +116,47 @@ Add this to your `settings.json` file inside the build root's `.vscode` folder:
```

`python.analysis.extraPaths` lets VSCode know where to find Pants's source root. The other config enables `black` and `flake8`.

## Alternative with the Dev Container

:::note We would love your feedback
The *Development Container* for Pants is still in its early stages. Please let us know if you encounter any issues or have suggestions for improvement.
:::

This project provides a *Development Container* (or [Dev Container](https://containers.dev/) for short) with a full-featured development environment containing all the tools, libraries, and runtimes needed to work with the [Pants](https://github.com/pantsbuild/pants) codebase. Here are some advantages of using dev containers:

- **Faster setup**: Dev containers can be pre-built with all the necessary tools, libraries and runtimes, making setting up a new development environment faster. This is especially useful for new team members joining a project who can quickly get started without spending time setting up their development environment.
- **Portability**: Dev containers provide portability between different platforms and clouds, allowing developers to write once and run anywhere. This ensures that developers can use the same development environment across different machines and platforms without compatibility issues.
- **Consistency**: Dev containers provide a consistent development environment for all developers working on a project. This ensures that everyone is using the same tools, libraries and runtimes, reducing the chances of compatibility issues and making it easier to collaborate and reproduce bugs.
- **Isolation**: Dev containers run in isolation from the host system, which improves security and reduces the chances of conflicts with other software installed on the host system.
- **Reproducibility**: Dev containers can be version-controlled, making it easy to reproduce the development environment at any point in time. It also allows developers to roll back to an earlier environment version if necessary.

### Features

- [Rust](https://www.rust-lang.org/) engine and common Rust utilities
- [Python](https://www.python.org/) 3.11
- [Docker-in-Docker](https://github.com/devcontainers/features/tree/main/src/docker-in-docker) (DinD)
- [Shell History](https://github.com/stuartleeks/dev-container-features/tree/main/src/shell-history)
- [Local Git hooks](https://www.pantsbuild.org/stable/docs/contributions/development/setting-up-pants#step-3-set-up-a-pre-push-git-hook)
- Useful VS Code extensions like `Python`, `Pylance`, `Black Formatter`, `rust-analyser`, `Even Better TOML`, etc.
- Volumes for Pants [cache directories](https://www.pantsbuild.org/stable/docs/using-pants/using-pants-in-ci#directories-to-cache)
- `hyperfine`, `py-sy`, `memray` and `dbg` for [debugging and benchmarking](https://www.pantsbuild.org/stable/docs/contributions/development/debugging-and-benchmarking)

### Getting started

You need three (3) things to get started with development containers:

- [VS Code](https://code.visualstudio.com/)
- [Docker](https://www.docker.com/)
- [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension for VS Code

More on getting started can be found [here](https://code.visualstudio.com/docs/devcontainers/containers#_getting-started).

### Using the Dev Container

1. After forking and cloning `pantsbuild/pants`, start VS Code and run the `Dev Containers: Open Folder in Container...` command from the *Command Palette...* (`F1`) and select the Pants project folder.
2. The VS Code window (instance) will reload and start building the dev container. A progress notification provides status updates.
3. After the build completes, VS Code will automatically connect to the container. You can now work with the repository source code in this independent environment.
4. Pants sets up its development virtualenv at `~/.cache/pants/pants_dev_deps/<venv_fingerprint>.venv/`. Point VS Code to the `bin/python` file in this folder by running the `Python: Select Interpreter` command from the *Command Palette...* (`F1`), and then `Enter interpreter path...`. You may need to restart your *terminal*. See [Configure your IDE (optional)](https://www.pantsbuild.org/docs/contributor-setup#configure-your-ide-optional).

More on starting a dev container can be found [here](https://code.visualstudio.com/docs/devcontainers/containers#_picking-your-quick-start).
Loading

0 comments on commit a6340b7

Please sign in to comment.