From c7c361956a38fc4e5126085047207e461af66f04 Mon Sep 17 00:00:00 2001 From: suiiibhit Date: Wed, 20 May 2026 01:49:13 +1000 Subject: [PATCH] docs: Add Codespaces setup to CONTRIBUTING.md Additionally, configure `prek` hooks in Codespaces. Signed-off-by: suiiibhit Co-authored-by: Matt Wozniski --- .devcontainer/devcontainer.json | 2 +- CONTRIBUTING.md | 34 +++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index edb23794..b22ad793 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -5,5 +5,5 @@ "dockerfile": "../Dockerfile" }, "runArgs": ["--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined"], - "onCreateCommand": "pip install -e ." + "onCreateCommand": "pip install -e . && prek install" } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 33615eeb..be408dea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,6 +11,40 @@ You can also search this project for issues with the following labels: | [help wanted](https://github.com/bloomberg/pystack/search?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+&type=Issues&utf8=%E2%9C%93) | `is:issue is:open label:"help wanted"` | General issues where contributors help is wanted. | | [question](https://github.com/bloomberg/pystack/search?q=is%3Aissue+is%3Aopen+label%3Aquestion&type=Issues&utf8=%E2%9C%93) | `is:issue is:open label:question` | Open discussions to resolve everything from implementation details to desired functionality. | +## Setting up a development environment + +### GitHub Codespaces + +The repository ships with a dev container configuration that works with +[GitHub Codespaces](https://github.com/features/codespaces). You can open +a ready-to-use environment directly: + +[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/bloomberg/pystack) + +Once the codespace is ready, all dependencies will be installed and hooks +will be configured automatically. + +Note that the dev container is built from the project's `Dockerfile`, which +compiles `elfutils` from source, so the first build takes a few minutes. + +pystack requires elevated ptrace permissions to inspect processes — the dev +container already handles this via `--cap-add=SYS_PTRACE` and +`seccomp=unconfined`, so things should work out of the box. + +### Local setup + +You'll need Linux with `libdw`, `libelf`, CMake, and a C++ compiler (Clang or +GCC). Then: + +```shell +git clone https://github.com/bloomberg/pystack.git pystack +cd pystack +python3 -m venv ../pystack-env/ +source ../pystack-env/bin/activate +pip install -e . -r requirements-test.txt -r requirements-extra.txt +prek install +``` + ## Contribution Licensing Since this project is distributed under the terms of an [open source license](LICENSE),