From da1f7d7458fb578c69830e09492823e11e976048 Mon Sep 17 00:00:00 2001
From: "Ilya (Marshal)" <ilya@marshal.dev>
Date: Thu, 27 Nov 2025 17:26:42 +0100
Subject: [PATCH 1/2] Add CONTRIBUTING.md

---
 CONTRIBUTING.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..fc1a861
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,80 @@
+## Contibuting to python-libipld
+
+This project is a small, single-file wrapper around Rust crates like `cid`, `cbor4ii`, and `multibase`, exposing a Python API through `PyO3`. Despite its size, performance matters a lot.
+
+The project uses `uv` package manager. Installing UV: https://docs.astral.sh/uv/getting-started/installation/
+
+Commands for quick start:
+```shell
+# install deps
+uv sync --group all
+
+# compile and install using maturin directly (faster and better for developing)
+uv run maturin develop
+
+# compile and install using pip and maturin backend
+uv pip install -v -e .
+
+# run all tests
+uv run pytest
+
+# run the most important benchmarks
+uv run pytest . -m benchmark_main
+
+# run lint and fmt
+cargo clippy && cargo fmt
+```
+
+### Performance
+
+Two key points:
+
+1. Python-side benchmarks
+
+    We use `pytest-benchmark` and run all benchmarks from the Python side. `CodSpeed` is used in CI/CD, but it relies on CPU simulation. The best comparison is always on your local machine.
+
+    First, capture the baseline from the `main` branch. This records performance relative to your hardware:
+    ```shell
+    # clone and checkout main branch
+    uv pip install -v -e .  
+    # run the most important benchmarks
+    uv run pytest . -m benchmark_main --benchmark-enable --benchmark-save=main
+    ```
+
+    Then, on your feature branch, run the same benchmarks but save under a different name (`--benchmark-save` argument)
+    ```shell
+    # checkout your branch
+    uv pip install -v -e .
+    uv run pytest . -m benchmark_main --benchmark-enable --benchmark-save=your_feature
+    ```
+
+    Finally, compare results:
+    ```shell
+    uv run pytest-benchmark compare --group-by="name" 
+    ```
+
+    Notes:
+    - Benchmark data is stored under `.benchmarks`.
+    - You can delete old snapshots during local development.
+
+2. Rust-side benchmarks
+
+    We also maintain Rust benchmarks, but they mainly exist for profiling and diagnosing performance issues. They work better with tools like flamegraph than when forced into a Python boundary. See the project's [Makefile](Makefile) for details.
+
+### Testing
+
+All tests target the Python-facing API, which is why the `pytest` directory exists.
+
+Any segfaults or Rust panics **must** be handled safely and must never crash the Python interpreter. Every error must be catchable at the Python layer.
+
+### Style
+
+Use `cargo fmt` and `cargo clippy`. CI will block your PR if formatting or linting fails.
+
+### Things to care about
+
+This library is used in:
+- DAG-CBOR benchmarks for Python: https://github.com/DavidBuchanan314/dag-cbor-benchmark
+- DASL Testing: https://hyphacoop.github.io/dasl-testing/
+
+Keep these in mind and consider running their test suites against your feature branch locally.

From 00c90215691e6bcd0b43cc24ee53e38cfd5bfe09 Mon Sep 17 00:00:00 2001
From: "Ilya (Marshal)" <ilya@marshal.dev>
Date: Thu, 27 Nov 2025 17:29:36 +0100
Subject: [PATCH 2/2] fix command

---
 CONTRIBUTING.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index fc1a861..bdd44cb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -19,7 +19,7 @@ uv pip install -v -e .
 uv run pytest
 
 # run the most important benchmarks
-uv run pytest . -m benchmark_main
+uv run pytest . -m benchmark_main --benchmark-enable
 
 # run lint and fmt
 cargo clippy && cargo fmt