From 5e3faa5367ba6092d63959f5919dc80ad33a3340 Mon Sep 17 00:00:00 2001
From: bronsen <kontakt+gitcommit@nrrd.de>
Date: Sun, 15 Feb 2026 17:25:51 +0100
Subject: [PATCH] doc: extend README.md

closes #10
---
 README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 77 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 3eb8c7e..77c0da9 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,7 @@
 # Teilchensammler
 
 This is a little TUI based on [Textual] for entering new Teilchen and for
-searching for existing Teilchen.
-
-Data will eventuall be stored in a SQLite database.
+searching for existing Teilchen. Data is kept in a sqlite database.
 
 ## Running tests
 
@@ -13,30 +11,102 @@ uv run pytest tests.py
 
 ## Observing the app's console
 
-You will need two terminals: one for showing the console, the other to run the app.
+The console can be used to observe log messages, since those logs really should
+not go to the terminal.
 
-Since we use uv the incantation is bit different from the official documenation:
+You will need two terminals:
+
+  1. one for showing the console,
+  2. the other to run the app.
+
+Since we use uv, the incantation is bit different from the official documenation:
 
 In one terminal:
 
 ```shell
-textual console
+uv run textual console
 ```
 
 And in the other:
 
 ```shell
+#  run,textual,run! ;)
 uv run textual run --dev src/teilchensammler_cli/__init__.py
 ```
 
+## Developing
+
+To re-create bronsen's development environment, you need several shiny new toys:
+
+* [just] to run the recipes from `justfile` (think Makefile, but easier)
+* [uv] for all the python executing stuff, also venv
+* [prek] as a replacement for pre-commit
+* [ruff] to lint and format the python code
+* [markdownlint-cli2] to keep some sort of consistency in our markdowns
+
+I use just; just uses uv, prek, ruff, and so on. It's indirection and
+abstraction all the way down.
+
+However, you can also do without all these!
+
+### Merge Requests
+
+You know how these work.
+
+### Commit style
+
+I prefer simple commit titles, and am not a fan of conventional commits. Do
+provide as much detail as desired in the message's body. Commit early, commit
+often; rebase frequently.
+
+### Tests
+
+Yes! Please write tests: simple ones, trivial ones; complicated ones, slow ones.
+
+Tests must be written in pytest fashion. Use all the plugins. Tests and
+fixtures should go into `tests.py`, until such time the file become too big and
+unwieldy.
+
+## Bug Reports, Feature Requests
+
+Create them [under "Issues"] at the top the [repo page]. Do not worry too much
+about labels.
+
+Please be specific and provide logs, screenshots, a test that replicates the
+problem.
+
+### Architectural Changes
+
+These are unlikely to be accepted. This tool is not intended to scale. There
+might be web-frontend thing automatically provided by [Textual].
+
+### Configs for tools the bronsen does not currently use
+
+Oh sure, I'll accept those. Please create a merge request that adds the file.
+I'll make an effort to update those to the best of my capabilities.
+
+## AI
+
+Please no: this is my little human-created thing.
+
 ## Creating a new release
 
+(This is so bronsen can forget.)
+
 * make code changes
-* add tests; make them pass
+* run tests; make them pass
 * commit
 * `git tag vX.Y.Z`
 * push commits and tags
 
 `uv build` will now create correctly named tar balls and wheels.
 
+----
+
 [Textual]: https://textual.textualize.io/
+[uv]: https://astral.sh/uv
+[just]: https://just.systems/
+[prek]: https://prek.j178.dev/
+[ruff]: https://astral.sh/ruff
+[markdownlint-cli2]: https://github.com/DavidAnson/markdownlint-cli2
+[under "Issues"]: https://code.c-base.org/infuanfu/teilchensammler-cli/issues/new