From 66ff339bb992ef70a66f236db2b5ad366d871d5c Mon Sep 17 00:00:00 2001
From: Copilot <198982749+Copilot@users.noreply.github.com>
Date: Wed, 24 Jun 2026 16:55:59 +0800
Subject: [PATCH] Add dedicated CONTRIBUTING guide and wire it from README
 (#521)

* Initial plan

* docs: add contributing guide and link from README

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
---
 CONTRIBUTING.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |  2 +-
 2 files changed, 72 insertions(+), 1 deletion(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..517d17c6
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,71 @@
+# Contributing to pocketpy
+
+Thank you for your interest in contributing to pocketpy.
+
+## Development Environment
+
+### Prerequisites
+
+- Python 3
+- CMake 3.10+
+- A C11 compiler
+  - Linux/macOS: `clang` or `gcc`
+  - Windows: MSVC (recommended)
+
+### Clone the repository
+
+```bash
+git clone --recursive https://github.com/pocketpy/pocketpy.git
+cd pocketpy
+```
+
+## Build from Source
+
+A standard local build:
+
+```bash
+python cmake_build.py Release
+```
+
+A build with optional modules (same style as CI):
+
+```bash
+python cmake_build.py Release -DPK_BUILD_MODULE_LZ4=ON -DPK_BUILD_MODULE_CUTE_PNG=ON -DPK_BUILD_MODULE_MSGPACK=ON
+```
+
+Build outputs are copied to the repository root (`main`, and `libpocketpy.so`/`pocketpy.dll`/`libpocketpy.dylib` when available).
+
+## Run Tests
+
+Run unit tests:
+
+```bash
+python scripts/run_tests.py
+```
+
+Run benchmarks:
+
+```bash
+python scripts/run_tests.py benchmark
+```
+
+On Linux, you can run the existing coverage script:
+
+```bash
+bash run_tests.sh
+```
+
+## Notes for Contributors
+
+- `python cmake_build.py` and `bash run_tests.sh` run `python prebuild.py` automatically.
+- If you edit files under `python/`, regenerate embedded sources with:
+
+```bash
+python prebuild.py
+```
+
+## Pull Requests
+
+- Keep changes focused and minimal.
+- Add/update tests when code behavior changes.
+- Open a PR with a clear summary of what changed and why.
diff --git a/README.md b/README.md
index b5f53a95..d99186ca 100644
--- a/README.md
+++ b/README.md
@@ -206,7 +206,7 @@ Submit a pull request to add your project here.
 
 ## Contribution
 
-All kinds of contributions are welcome.
+All kinds of contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, build, testing, and PR guidance.
 
 - Submit a Pull Request
   - fix a bug