An deciwa arbeiten

Wie die Docs funktionieren und wie aus einem Vorschlag eine Entscheidung wird. Das Repository und seine Pakete: Technischer Überblick.

Die Docs sind die Wahrheit

Diese Docs sind die einzige Quelle der Wahrheit für alle, die deciwa entwickeln. Entscheidungen sind Anforderungen: jedes Feature und jedes Stück Code muss zu ihnen passen. Jede Aussage ist ein Sphinx-Needs-Objekt mit ID und Status.

Objekt	Präfix	Status	Bedeutung
Entscheidung	DEC_	approved	von Daniel entschieden – verbindlich
Vorschlag	PROP_	draft → review → approved / rejected	Teil der technischen Details einer Version, noch nicht verbindlich
Frage	Q_	open → answered	jemand muss etwas entscheiden – siehe Offene Fragen

Ein freigegebener Vorschlag wird zur Entscheidung: er bekommt ein DEC_-Objekt in Entscheidungen, und die technische Seite verlinkt darauf.

Produktbeschreibung, Integrationen, Entscheidungen und technische Details liegen in docs/ als Markdown (MyST). Die HTML-Seiten werden erzeugt; niemand bearbeitet sie.

$ uv sync                                                         # packages + docs tools
$ .venv/bin/sphinx-autobuild docs docs/_build/html --port 4336   # live preview
$ .venv/bin/sphinx-build -W -b html docs docs/_build/html         # CI build, warnings fail

Veröffentlichte Docs

.github/workflows/docs.yml prüft die Docs (Warnungen lassen den Build scheitern) bei jedem Push und Pull Request. Von main aus veröffentlicht es sie im Branch gh-pages des öffentlichen Repositorys danwos/deciwa.docs, dessen GitHub Pages sie unter https://deciwa.danwos.dev ausliefern – der Code hier bleibt privat. Der veröffentlichte Build ist ein Offline-Review-Build ohne die Review-Daten aus .deciwa/, damit Besucher deciwa auf diesen Seiten in ihrem eigenen Browser ausprobieren können.

Übersetzungen

Die Docs erscheinen auf Englisch und Deutsch; weitere Sprachen können auf demselben Weg folgen.

Vorschlag: Englisch ist die Quelle der Docs; Deutsch ist eine Übersetzung in gettext-Katalogen PROP_DOCS_TRANSLATION

status: draft refines: DEC_DOCS_IN_REPO refined by: PROP_DOCS_REVIEW_SOURCE, Q_OVERLAY_LANGUAGE

Alle schreiben und ändern das englische Markdown. Die Übersetzungen liegen in docs/locales/<language>/LC_MESSAGES/*.po, ein Katalog pro Seite plus needs.po für Titel und Felder der Needs. Ändert sich ein englischer Absatz, wird seine Übersetzung fuzzy, und die alte bleibt sichtbar, bis jemand sie aktualisiert. Englisch erscheint im Wurzelverzeichnis, Deutsch unter de/; ein Umschalter in der Seitenleiste führt zur selben Seite in der anderen Sprache.

Vorschlag: Reviews und Entscheidungen finden nur auf den englischen Docs statt PROP_DOCS_REVIEW_SOURCE

status: draft refines: PROP_DOCS_TRANSLATION

Eine Übersetzung wird geprüft wie jede Formulierung, verbindlich ist aber die englische Aussage: .deciwa/ enthält nur Reviews der englischen Seiten. Die deutschen Seiten tragen das Overlay nur als Offline-Demo für Besucher.

Frage: Soll das Overlay auf deutschen Seiten Deutsch sprechen? Q_OVERLAY_LANGUAGE

status: open to: Daniel refines: PROP_DOCS_TRANSLATION

Heute ist jede Beschriftung des Overlays englisch. Es könnte seine Sprache aus <html lang> nehmen und pro Sprache ein kleines Wörterbuch mitbringen.

Die Kataloge nach einer Änderung an den englischen Docs aktualisieren:

$ .venv/bin/sphinx-build -E -b gettext -D needs_build_json=0 docs docs/_build/gettext
$ .venv/bin/sphinx-intl update -p docs/_build/gettext -d docs/locales -l de
$ .venv/bin/sphinx-intl stat -d docs/locales -l de                  # what is left to translate
$ .venv/bin/sphinx-build -W -b html -D language=de docs docs/_build/html/de

Diese Docs in deciwa reviewen

Diese Docs nutzen die Sphinx-Integration selbst: uv sync, dann .venv/bin/deciwa serve und http://127.0.0.1:4337 öffnen. Was freigegeben werden muss, steht in .deciwa/config.toml (heute: jedes Need). Der ganze Ablauf – reviewen, mit deciwa todo / deciwa resolve arbeiten, neu bauen – steht im Workflow.

Einen prop freizugeben oder eine question zu beantworten ist in deciwa die Entscheidung; der Vorschlag wird dann wie unten beschrieben zu einem dec.

Vom Vorschlag zur Entscheidung

1. Die technischen Details der nächsten Version liegen in technical/ (heute für 0.1). Jede Aussage, die eine Entscheidung braucht, ist ein prop mit Status draft.

2. Jeder offene Punkt ist eine question, deren to: nennt, wer entscheidet.

3. Ist eine Seite bereit fürs Review, gehen ihre Vorschläge auf review.

4. Daniel entscheidet: ein Vorschlag wird approved oder rejected, eine Frage wird answered.

5. Jeder freigegebene Vorschlag bekommt einen dec in decisions/index.md mit decided, reason und alternatives; die Produktseiten werden passend aktualisiert. Die technische Seite kann dann auf das gekürzt werden, was noch offen ist.

Objekte

```{dec} Short statement of the decision
:id: DEC_SOMETHING
:status: approved
:decided: 2026-10-19
:reason: Why.
:alternatives: What else was considered.
```

Typ	Präfix	Felder
dec	DEC_	decided, reason, alternatives
prop	PROP_	refines – die Entscheidungen, die er ausführt
question	Q_	to, answers / refines

Ein Objekt im Text referenzierst du mit {need}`DEC_SOMETHING`.

Code

Der Code ist in Pakete aufgeteilt – Pakete. Logik gehört in deciwa-core; Frontends nutzen nur deciwa.core.Project.

Code folgt den Entscheidungen. Passen Code und eine Entscheidung nicht zusammen, gewinnt die Entscheidung – oder ein neuer Vorschlag ändert zuerst die Entscheidung.