From d8d32e1662a63924a116bb65d27fcbcaf77e64f4 Mon Sep 17 00:00:00 2001
From: Tiara Rodney <tiara.rodney@byteb4rb1e.me>
Date: Sat, 21 Mar 2026 18:35:12 +0100
Subject: [PATCH] docs: add development guidelines

---
 DEVELOPMENT.md | 122 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 122 insertions(+)
 create mode 100644 DEVELOPMENT.md

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..93093de
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,122 @@
+# Development
+
+> All changes MUST follow the vendor/tiara-gitflow-spec.git and no work MUST be
+> started without a TODO issue.
+
+## Prerequisites
+
+- Python 3.9+
+- [Pipenv](https://pipenv.pypa.io/)
+- [tox](https://tox.wiki/) (installed via Pipenv dev dependencies)
+- Node.js (for the `@byteb4rb1e/mime-todo` issue tracker CLI)
+
+## Setup
+
+Iniitialize Git submodules:
+
+```bash
+git submodule update --init --remote --recursive
+```
+
+Install dependencies (includes the package in editable mode):
+
+```bash
+pipenv install --dev
+```
+
+
+## Tooling
+
+### Package
+
+The project is packaged as `byteb4rb1e.utils` under a namespace package
+layout (`src/byteb4rb1e/utils/`). It is installed in editable mode via
+Pipenv.
+
+Build a distribution:
+
+```bash
+pipenv run dist
+```
+
+### Testing
+
+Tests are managed by tox. Test environments are defined in `tox.ini`:
+
+```bash
+# run all test suites
+tox
+
+# run specific environments
+tox -e unit-py313
+tox -e lint
+tox -e format
+```
+
+| Environment | Purpose |
+|---|---|
+| `unit-py3{9-13}` | Unit tests |
+| `smoke-py3{9-13}` | Smoke tests |
+| `integration-py3{9-13}` | Integration tests |
+| `lint` | Type checking (mypy) |
+| `format` | Code style (autopep8) |
+| `audit` | Dependency audit (pip-audit) |
+
+### Issue tracker
+
+Issues are tracked in the `TODO` file using the
+[MIME TODO](https://specs.code.tiararodney.com/mime-todo/) format. Use the
+`@byteb4rb1e/mime-todo` CLI to interact with it:
+
+```bash
+# list issues
+npx @byteb4rb1e/mime-todo list
+
+# show a specific issue
+npx @byteb4rb1e/mime-todo show 3
+
+# create an issue
+npx @byteb4rb1e/mime-todo create --type feature --title "Title" --plan "Description" --module homeostat
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full issue lifecycle.
+
+### Publishing
+
+Build wheel and source distributions:
+
+```sh
+pipenv run sdist
+```
+
+Configure publishing options:
+
+`~/.pypirc`
+```
+[distutils]
+index-servers =
+    tiararodney
+
+[tiararodney]
+repository: https://pypi.code.tiararodney.com/root/byteb4rb1e/
+username: <username>
+password: <password>
+```
+
+Publish to pypi.code.tiararodney.com:
+
+```sh
+pipenv run sdist:publish:tiarardoney
+```
+
+
+## Project layout
+
+```
+src/byteb4rb1e/utils/        # package source
+tests/                       # test suites (unit/, smoke/, integration/)
+vendor/                      # vendored specs
+dist/                        # sdist and wheel build output 
+DEVELOPMENT.md               # this file
+TODO                         # issue tracker (MIME TODO format)
+```