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

@@ -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.

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

include/pocketpy/pocketpy.h

@@ -800,6 +800,9 @@ PK_API char* py_profiler_report();
 /************* Others *************/
 int64_t time_ns();
 int64_t time_monotonic_ns();
+py_i64 cpy11__int_floordiv(py_i64 a, py_i64 b);
+py_i64 cpy11__int_mod(py_i64 a, py_i64 b);
+void cpy11__float_divmod(double vx, double wx, double *floordiv, double *mod);
 
 /// An utility function to read a line from stdin for REPL.
 PK_API int py_replinput(char* buf, int max_size);

src/bindings/py_number.c

@@ -127,7 +127,7 @@ static bool number__pow__(int argc, py_Ref argv) {
 
 static py_i64 i64_abs(py_i64 x) { return x < 0 ? -x : x; }
 
-py_i64 cpy11__fast_floor_div(py_i64 a, py_i64 b) {
+py_i64 cpy11__int_floordiv(py_i64 a, py_i64 b) {
     assert(b != 0);
     if(a == 0) return 0;
     if((a < 0) == (b < 0)) {
@@ -137,7 +137,7 @@ py_i64 cpy11__fast_floor_div(py_i64 a, py_i64 b) {
     }
 }
 
-py_i64 cpy11__fast_mod(py_i64 a, py_i64 b) {
+py_i64 cpy11__int_mod(py_i64 a, py_i64 b) {
     assert(b != 0);
     if(a == 0) return 0;
     py_i64 res;
@@ -150,7 +150,7 @@ py_i64 cpy11__fast_mod(py_i64 a, py_i64 b) {
 }
 
 // https://github.com/python/cpython/blob/3.11/Objects/floatobject.c#L677
-static void cpy11__float_div_mod(double vx, double wx, double *floordiv, double *mod)
+void cpy11__float_divmod(double vx, double wx, double *floordiv, double *mod)
 {
     double div;
     *mod = dmath_fmod(vx, wx);
@@ -193,7 +193,7 @@ static bool int__floordiv__(int argc, py_Ref argv) {
     if(py_isint(&argv[1])) {
         py_i64 rhs = py_toint(&argv[1]);
         if(rhs == 0) return ZeroDivisionError("integer division by zero");
-        py_newint(py_retval(), cpy11__fast_floor_div(lhs, rhs));
+        py_newint(py_retval(), cpy11__int_floordiv(lhs, rhs));
     } else {
         py_newnotimplemented(py_retval());
     }
@@ -206,7 +206,7 @@ static bool int__mod__(int argc, py_Ref argv) {
     if(py_isint(&argv[1])) {
         py_i64 rhs = py_toint(&argv[1]);
         if(rhs == 0) return ZeroDivisionError("integer modulo by zero");
-        py_newint(py_retval(), cpy11__fast_mod(lhs, rhs));
+        py_newint(py_retval(), cpy11__int_mod(lhs, rhs));
     } else {
         py_newnotimplemented(py_retval());
     }
@@ -220,7 +220,7 @@ static bool float__floordiv__(int argc, py_Ref argv) {
     if(try_castfloat(&argv[1], &rhs)) {
         if(rhs == 0.0) return ZeroDivisionError("float modulo by zero");
         double q, r;
-        cpy11__float_div_mod(lhs, rhs, &q, &r);
+        cpy11__float_divmod(lhs, rhs, &q, &r);
         py_newfloat(py_retval(), q);
         return true;
     }
@@ -235,7 +235,7 @@ static bool float__rfloordiv__(int argc, py_Ref argv) {
     if(try_castfloat(&argv[1], &lhs)) {
         if(rhs == 0.0) return ZeroDivisionError("float modulo by zero");
         double q, r;
-        cpy11__float_div_mod(lhs, rhs, &q, &r);
+        cpy11__float_divmod(lhs, rhs, &q, &r);
         py_newfloat(py_retval(), q);
         return true;
     }
@@ -250,7 +250,7 @@ static bool float__mod__(int argc, py_Ref argv) {
     if(try_castfloat(&argv[1], &rhs)) {
         if(rhs == 0.0) return ZeroDivisionError("float modulo by zero");
         double q, r;
-        cpy11__float_div_mod(lhs, rhs, &q, &r);
+        cpy11__float_divmod(lhs, rhs, &q, &r);
         py_newfloat(py_retval(), r);
         return true;
     }
@@ -265,7 +265,7 @@ static bool float__rmod__(int argc, py_Ref argv) {
     if(try_castfloat(&argv[1], &lhs)) {
         if(rhs == 0.0) return ZeroDivisionError("float modulo by zero");
         double q, r;
-        cpy11__float_div_mod(lhs, rhs, &q, &r);
+        cpy11__float_divmod(lhs, rhs, &q, &r);
         py_newfloat(py_retval(), r);
         return true;
     }
@@ -280,7 +280,7 @@ static bool float__divmod__(int argc, py_Ref argv) {
     if(try_castfloat(&argv[1], &rhs)) {
         if(rhs == 0.0) return ZeroDivisionError("float modulo by zero");
         double q, r;
-        cpy11__float_div_mod(lhs, rhs, &q, &r);
+        cpy11__float_divmod(lhs, rhs, &q, &r);
         py_Ref p = py_newtuple(py_retval(), 2);
         py_newfloat(&p[0], q);
         py_newfloat(&p[1], r);
@@ -296,8 +296,8 @@ static bool int__divmod__(int argc, py_Ref argv) {
     py_i64 rhs = py_toint(&argv[1]);
     if(rhs == 0) return ZeroDivisionError("integer division or modulo by zero");
     py_Ref p = py_newtuple(py_retval(), 2);
-    py_newint(&p[0], cpy11__fast_floor_div(lhs, rhs));
+    py_newint(&p[0], cpy11__int_floordiv(lhs, rhs));
-    py_newint(&p[1], cpy11__fast_mod(lhs, rhs));
+    py_newint(&p[1], cpy11__int_mod(lhs, rhs));
     return true;
 }
 

src/modules/vmath.c

@@ -8,8 +8,8 @@
 
 static bool isclose(float a, float b) { return dmath_fabs(a - b) < 1e-4; }
 
-py_i64 cpy11__fast_floor_div(py_i64 a, py_i64 b);
+py_i64 cpy11__int_floordiv(py_i64 a, py_i64 b);
-py_i64 cpy11__fast_mod(py_i64 a, py_i64 b);
+py_i64 cpy11__int_mod(py_i64 a, py_i64 b);
 
 #define DEFINE_VEC_FIELD(name, T, Tc, field)                                                       \
     static bool name##__##field(int argc, py_Ref argv) {                                           \
@@ -317,7 +317,7 @@ DEF_VECTOR_OPS(3)
         c11_vec##D##i a = py_tovec##D##i(&argv[0]);                                                \
         py_i64 b = py_toint(&argv[1]);                                                             \
         for(int i = 0; i < D; i++)                                                                 \
-            a.data[i] = cpy11__fast_floor_div(a.data[i], b);                                       \
+            a.data[i] = cpy11__int_floordiv(a.data[i], b);                                       \
         py_newvec##D##i(py_retval(), a);                                                           \
         return true;                                                                               \
     }                                                                                              \
@@ -327,7 +327,7 @@ DEF_VECTOR_OPS(3)
         c11_vec##D##i a = py_tovec##D##i(&argv[0]);                                                \
         py_i64 b = py_toint(&argv[1]);                                                             \
         for(int i = 0; i < D; i++)                                                                 \
-            a.data[i] = cpy11__fast_mod(a.data[i], b);                                             \
+            a.data[i] = cpy11__int_mod(a.data[i], b);                                             \
         py_newvec##D##i(py_retval(), a);                                                           \
         return true;                                                                               \
     }