From 1d411b695891cf5dcec6d58ffd756b50eac606b5 Mon Sep 17 00:00:00 2001
From: Olaf Mersmann <olafm@p-value.net>
Date: Fri, 17 Nov 2023 11:47:13 +0100
Subject: [PATCH] [doc] Add developer documentation

Since switching away from do.yp to scripts/fabricate, the developer
experience has changed drastically. This commit starts adding more
formal documentation on how a developer interacts with the code
base.

Resolves #2230
Partially fixes #2238
---
 DEVELOPMENT.md | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 DEVELOPMENT.md

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 000000000..079200d69
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,95 @@
+Working with the `coco` code base
+=================================
+
+## Vefore you start
+
+## Getting Started
+
+## Working with the Experimental Code
+
+### Running unit tests
+
+Change to the unit tests directory
+```sh
+cd code-experiments/test/unit-test
+```
+
+Rerun `fabricate` if not already done
+```sh
+python ../../../scripts/fabricate
+```
+
+Build tests using [`cmake`](https://cmake.org/cmake/help/latest/manual/cmake.1.html)
+```sh
+cmake -B build
+cmake --build build
+```
+
+Run tests using [`ctest`](https://cmake.org/cmake/help/latest/manual/ctest.1.html)
+```sh
+ctest --test-dir build     
+```
+
+## Regression tests
+
+Note that I'm not sure the regression tests are really useful at the moment. But here goes:
+
+Change to the regression tests directory
+```sh
+cd code-experiments/test/regression-test
+```
+
+The regression tests require the `cocoex` Python package. Install it first
+```sh
+pip uninstall -y cocoex
+pip install ../../build/python/  
+```
+
+Now run the regression tests
+
+```sh
+python test_suites.py   
+```
+and 
+```sh
+python test_logger.py
+```
+
+## Integration tests
+
+Still need to fix those up.
+
+## `cocoex` Python package
+
+Change to the `cocoex` Python package directory
+```sh
+cd code-experiments/build/python
+```
+
+Install the package from source
+```sh
+pip uninstall -y cocoex
+pip install .
+```
+
+Install and run `pytest`
+```sh
+pip install pytest
+python -m pytest test
+```
+
+## Working with the Postprocessing Code
+
+Before you begin, always run python scripts/fabricate to update any auto-generated files. Then, you can install the `cocopp` package using pip:
+
+```sh
+python -m pip uninstall -y cocopp
+python -m pip install code-postprocessing
+```
+
+If you are working on `cocopp`, you can use an editable install and Python will pick up any changes you make without having to reinstall:
+
+```sh
+python -m pip uninstall -y cocopp
+python -m pip install --editable code-postprocessing
+```