add dev docs (draft)

docs/source/development.md

@@ -0,0 +1,80 @@
+# Development
+
+## Local development setup
+
+`menuinst` is a multiplatform tool with heavy reliance on OS-specific behaviour, APIs and tools.
+Each platform requires its own setup.
+
+> Since some tests might leave traces behind, we recommend running the tests from a VM (if you can).
+For your own protection, some tests only run when the `CI` env var has been set to a non-empty value. If you do want to run these on your local machine, you can set the `CI` env var to `1` before running the tests; it better be on a VM though!
+
+## Linux
+
+We recommend using Docker to run the tests on Linux. However, some tasks require a graphical environment.
+
+### Docker setup
+
+1. We can leverage `conda/conda`'s conda-forge-based CI image for this. Make sure to mount the `menuinst` source to a known location in the container. In the example below, we are using `~/my/repos/menuinst`, mapped to `/opt/menuinst-src`.
+
+```
+$ docker run -it --rm --platform=linux/aarch64 \
+    -v ~/my/repos/menuinst:/opt/menuinst-src \
+    ghcr.io/conda/conda-ci:main-linux-python3.10-conda-forge bash
+```
+
+2. Create a new conda environment and install the dependencies:
+
+```
+$ conda create -n menuinst-dev \
+    conda-canary/label/conda-conda-pr-11882::conda \
+    pip \
+    pytest \
+    pytest-cov \
+    pydantic \
+    hypothesis \
+    hypothesis-jsonschema
+```
+
+3. Activate the environment and install `menuinst`:
+
+```
+$ conda activate menuinst-dev
+$ python -m pip install -vv /opt/menuinst-src
+```
+
+4. Run the tests:
+
+```
+$ cd /opt/menuinst-src
+$ pytest
+```
+
+### VM setup
+
+## macOS
+
+Some of the tests involve modifying the system's menu. While we have added some teardown logic to
+undo the modifications once done, it might still leave some artifacts behind. We recommend running
+the tests from a VM (if you can).
+
+### VM setup with UTM
+
+This is recommended for Apple Silicon.
+
+1. Download [UTM](https://mac.getutm.app/) and create a new VM for macOS using the default
+   settings. The UI only requires a couple clicks, but the download and automated install will take a few hours, so be patient.
+
+### Debug in CI
+
+In extreme cases, you can edit the Github Actions workflow to add a step for [`mxschmitt/action-tmate`](https://github.com/marketplace/actions/debugging-with-tmate) and then connect to the VM via SSH. Please be mindful of the resources and only add it for the platforms and Python versions you need. For example:
+
+```yaml
+- name: Setup tmate session
+  uses: mxschmitt/action-tmate@v3
+  timeout-minutes: 60
+  if: ${{ failure() && matrix.os == 'macos-latest' && matrix.python-version == '3.9' }}
+```
+
+## Windows
+
+Some tests will add changes to your system configuration (Windows registry, new files added, etc). We try to clean up after ourselves, but it's not always possible. We recommend running the tests from a VM (if you can).

docs/source/index.md

@@ -11,4 +11,5 @@ getting-started
 defining-shortcuts
 conda
 reference
+development
 ```

news/131-add-dev-docs

@@ -0,0 +1,19 @@
+### Enhancements
+
+* <news item>
+
+### Bug fixes
+
+* <news item>
+
+### Deprecations
+
+* <news item>
+
+### Docs
+
+* Add development documentation. (#131)
+
+### Other
+
+* <news item>