From 5f93cc8b2c51f3440ebef9c7b0bb8e96b838d60a Mon Sep 17 00:00:00 2001
From: Nils Dijk <nils@citusdata.com>
Date: Thu, 3 Aug 2023 13:24:30 +0000
Subject: [PATCH] add section to CONTRIBUTING.md on devcontainers

---
 .devcontainer/Dockerfile |  4 ++++
 CONTRIBUTING.md          | 24 ++++++++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
index 2af79392a6d..91c027d5f2c 100644
--- a/.devcontainer/Dockerfile
+++ b/.devcontainer/Dockerfile
@@ -125,6 +125,7 @@ RUN sudo apt update \
  && sudo apt install -y \
     autoconf2.69 \
     bash-completion \
+    fswatch \
     gdb \
     htop \
     lsof \
@@ -172,3 +173,6 @@ RUN sudo chown --from=root:root citus:citus -R ~
 
 # sets default pg version
 RUN pgenv switch latest 15
+
+# make connecting to the coordinator easy
+ENV PGPORT=9700
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 66d026b8bd9..203d4d6b364 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -11,6 +11,30 @@ sign a Contributor License Agreement (CLA). For an explanation of
 why we ask this as well as instructions for how to proceed, see the
 [Microsoft CLA](https://cla.opensource.microsoft.com/).
 
+### Devcontainer / Github Codespaces
+
+The easiest way to start contributing is via our devcontainer. This container works both locally in visual studio code with docker-desktop/docker-for-mac as well as [Github Codespaces](https://github.com/features/codespaces). To open the project in vscode you will need the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). To start the project in Codespaces, please follow the guidance from Github
+
+With the extension installed you can run the following from the command pallet to get started
+
+```
+> Dev Containers: Clone Repository in Container Volume...
+```
+
+In the subsequent popup paste the url to the repo and hit enter.
+
+```
+https://github.com/citusdata/citus
+```
+
+This will create an isolated Workspace in vscode, complete with all tools required to build, test and run the Citus extension. We keep this container up to date with the supported postgres versions as well as the exact versions of tooling we use.
+
+To quickly start we suggest splitting your terminal once to have two shells. The left one in the `/workspaces/citus`, the second one changed to `/data`. The left terminal will be used to interact with the project, the right one with a testing cluster.
+
+To get citus installed from source we run `make install -sj8` in the first terminal, adjust `j8` to suite number of cores you have available. Once installed you can start a Citus cluster in the second terminal via `citus_dev make citus`. The cluster will run in the background, and can be interacted with via `citus_dev`. To get an overview of the available commands.
+
+With the Citus cluster running you can connect to the coordinator in the first terminal via `psql -p9700`. Because the coordinator is the most common entrypoint the `PGPORT` environment is set accordingly, so a simple `psql` will connect directly to the coordinator.
+
 ### Getting and building
 
 [PostgreSQL documentation](https://www.postgresql.org/support/versioning/) has a