From 0962abbfdbf1e01a9271832184ec4fb28d2aa11d Mon Sep 17 00:00:00 2001
From: Cem Basoglu <cem.basoglu@web.de>
Date: Thu, 20 Nov 2025 20:27:29 +0000
Subject: [PATCH] add devcontainer configuration for zha-device-handlers
 project

---
 .devcontainer/Dockerfile        | 22 ++++++++++
 .devcontainer/README.md         | 71 +++++++++++++++++++++++++++++++++
 .devcontainer/devcontainer.json | 22 ++++++++++
 3 files changed, 115 insertions(+)
 create mode 100644 .devcontainer/Dockerfile
 create mode 100644 .devcontainer/README.md
 create mode 100644 .devcontainer/devcontainer.json

diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 0000000000..854eb3055b
--- /dev/null
+++ b/.devcontainer/Dockerfile
@@ -0,0 +1,22 @@
+FROM mcr.microsoft.com/devcontainers/python:1-3.12
+
+USER root
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Install common build dependencies required for compiling Python packages
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        build-essential \
+        libffi-dev \
+        libssl-dev \
+        cargo \
+        git \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# Upgrade pip/setuptools to a modern version
+RUN python3 -m pip install --upgrade pip setuptools wheel
+
+USER vscode
+
+WORKDIR /workspaces/zha-device-handlers
diff --git a/.devcontainer/README.md b/.devcontainer/README.md
new file mode 100644
index 0000000000..0b26c18fb4
--- /dev/null
+++ b/.devcontainer/README.md
@@ -0,0 +1,71 @@
+# Devcontainer for `zha-device-handlers`
+
+This folder contains a [VS Code Dev Container](https://code.visualstudio.com/docs/devcontainers/containers) configuration for working on `zha-device-handlers` in a reproducible development environment.
+
+Using the devcontainer is **optional** and only affects contributors who choose to develop the project inside VS Code / Dev Containers or GitHub Codespaces.
+
+## What you get
+
+The devcontainer is based on `mcr.microsoft.com/devcontainers/python:1-3.12` and includes:
+
+* Python 3.12 with common build tools and system dependencies
+* A local virtual environment for the project
+* Development dependencies installed via `script/setup`
+* Recommended VS Code extensions for Python and testing
+* A consistent shell / tooling setup across contributors
+
+## Prerequisites
+
+To use the devcontainer locally, you need:
+
+* [Docker](https://www.docker.com/) running on your machine
+* [Visual Studio Code](https://code.visualstudio.com/)
+* The VS Code extension: **Dev Containers** (or **Remote - Containers** in older installs)
+
+Alternatively, you can use this configuration with **GitHub Codespaces**.
+
+## Getting started
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/zigpy/zha-device-handlers.git
+   cd zha-device-handlers
+   ```
+
+2. Open the folder in VS Code:
+
+   ```bash
+   code .
+   ```
+
+3. When prompted, click **"Reopen in Container"**.
+   VS Code will build the container image and start the devcontainer.
+
+4. After the container is created, the `postCreateCommand` will run:
+
+   ```bash
+   script/setup
+   ```
+
+   This creates a virtual environment and installs the necessary development dependencies inside the container.
+
+## Running tests and checks
+
+Inside the devcontainer terminal you can run the usual commands, for example:
+
+```bash
+# Run tests
+script/test
+
+# Run pre-commit checks
+pre-commit run --all-files
+```
+
+These commands run **inside** the container, so your host system stays clean and does not need extra Python versions or global packages.
+
+## Why use this?
+
+* Keeps your local system clean (no additional Python envs / deps required)
+* Provides a reproducible environment across contributors
+* Makes it easier for new contributors to get started (clone → open → develop)
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 0000000000..ca8d370697
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,22 @@
+{
+  "name": "zha-device-handlers (Dev)",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": ".."
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance"
+      ]
+    }
+  },
+  "postCreateCommand": "bash script/setup || true",
+  "remoteUser": "vscode",
+  "workspaceFolder": "/workspaces/zha-device-handlers",
+  "containerEnv": {
+    "PIP_NO_CACHE_DIR": "off",
+    "DEBIAN_FRONTEND": "noninteractive"
+  }
+}