doc: extend README.md

closes #10

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

justfile

@@ -46,10 +46,13 @@ lint: lint-python lint-markdown
 clean:
   rm dist/*.whl dist/*.tar.gz
 
-ci:
+ci: lint
   prek run --all-files
 #   woodpecker-cli exec "whatever"
 
 release:
   @echo remember to git tag and update pyproject.toml
   uv build
+  # upload to package registry
+  # send newsletter
+  # take over the world