Zusammen am Stack arbeiten

Questi contenuti non sono ancora disponibili nella tua lingua.

Ein Beitrag ist alles, was den Stack für die nächste Community besser macht: Code, eine Story, ein Satz in der Spec, ein Test mit echten Menschen, eine Grafik, eine bessere Erklärung. Der Weg ist für alle derselbe, und er braucht keinen bestimmten Agenten und keinen Runner.

Vor dem ersten Handgriff

Beschreibe das Problem oder den Nutzerweg, nicht die Lösung. Lies die Spec-Stelle, die das Verhalten festlegt, und suche das Beispiel im Storybook. Bei einer größeren Verhaltensänderung klärst du die Produktfrage vorher im Issue, sonst entstehen zwei Umsetzungen nebeneinander. Was Architektur ändert, wird vorher besprochen, nicht im PR entdeckt.

Der normale Weg

Ein Branch für einen überschaubaren Beitrag. Klein und prüfbar schlägt vollständig und groß; zwei PRs sind besser als einer, der zwei Dinge tut.
Verhalten, Code, Story, Test und Erklärung gemeinsam ändern. Berührt der Beitrag Items, Schemas, Module, Fähigkeiten, oder Hooks, geht die Spec mit: Entweder der Code folgt ihr, oder sie ändert sich sichtbar, mit Begründung im PR.
Die Prüfungen laufen lassen, die den Bereich betreffen (Lokal entwickeln → Prüfen).
Ein Pull Request mit Problem, Verhalten nach der Änderung und den tatsächlich ausgeführten Prüfungen. Der Titel folgt Conventional Commits (feat(toolkit): …, fix(network): …, docs(spec): …); CI prüft das, weil release-please daraus die Versionen ableitet.
Review. Zuerst reviewt meist ein Agent (Codex im Loop-Review, CodeRabbit), dann ein Mensch; Befunde werden im PR beantwortet und im selben Branch behoben. Die Merge-Entscheidung bleibt bei einem Menschen.

Was ein PR sichtbar macht

was sich geändert hat und warum,
welche Dateien betroffen sind,
welche Prüfungen liefen, und welche nicht laufen konnten und warum,
was offen ist und was ein Mensch entscheiden muss,
die Dokumentationswirkung: Ändert sich ein Begriff, ein Ablauf, ein öffentlicher Vertrag, ein Startbefehl? Welche Seiten und Stories wurden angepasst? Wenn keine, warum nicht?

Das Handbuch nennt je Seite seine Quellen im Frontmatter; pnpm check:site fällt, wenn eine fehlt. Ob eine Erklärung fachlich noch stimmt, prüft ein Mensch.

Sprache und Konventionen

Spec und Dokumentation sind Deutsch, Bezeichner im Code Englisch, Code-Kommentare in der Sprache ihrer Umgebung (im Toolkit Deutsch). Storybook ist Englisch, seine Beispieldaten Deutsch; die Sprache des Toolkits selbst schaltet der Umschalter „Language“ in der Werkzeugleiste. Normative Wörter in der Spec (MUSS, SOLLTE, DARF NICHT) folgen der Konvention der ganzen Familie in real-life-org/meta → CONVENTIONS.md; ein Wächter prüft sie.

Texte in der Oberfläche

Das Toolkit spricht Deutsch und Englisch. Welche Sprache gilt, bestimmt die Instanz (config.json: defaultLanguage), sonst der Browser (sofern er Deutsch oder Englisch spricht), sonst Englisch; eine Sprachwahl in der eigenen Oberfläche bietet das Toolkit nicht an. Baut eine App einen Umschalter, ruft sie beim Start enableLanguageChoice() auf: erst dann speichert setLanguage die Wahl, und eine gespeicherte Wahl geht der Instanz vor. Ohne diesen Aufruf wechselt setLanguage nur für die Sitzung, und eine früher gespeicherte Wahl bleibt liegen, ohne zu gelten. Ein Text, den Menschen sehen oder vorgelesen bekommen, steht nicht im Code, sondern als Schlüssel in packages/toolkit/src/i18n/de.ts (die Referenz) und en.ts (gegen de.ts getypt, ein fehlender Schlüssel bricht den Build). Fehlt einer App oder Instanz ein Text in der aktiven Sprache, gilt der englische, dann der deutsche. Komponenten holen ihn über useI18n().t("bereich.name", { platzhalter }), Code außerhalb von React über getI18n().t. Mengen sind Plural-Einträge ({ one, other } mit count), Namen und Zahlen Platzhalter; Sätze werden nie aus Bruchstücken zusammengesetzt. Meldungen an Entwickler (throw, console) bleiben Deutsch.

Ein Wächter hält den Rest fest: packages/toolkit/tests/i18n-guard.test.ts zählt je Datei, wo noch fester Text steht (JSX-Text, Anzeige-Attribute wie title, aria-label, placeholder, Props auf …Label/…Message, Literale in JSX-Kindern und deutsch aussehende Literale), und vergleicht mit i18n-baseline.json. Neue feste Texte machen ihn rot, abgebaute auch, bis die Baseline mitsinkt: pnpm --filter @real-life/toolkit i18n:baseline. Was er nicht lesen soll, nennt i18n-scan.ts mit Grund; einzelne Stellen nimmt ein Kommentar i18n-exempt: <Grund> aus.

Mit einem Agenten

Ein Agent schreibt Code wie ein Mensch, nur schneller und mit anderen Fehlern. Der Arbeitsablauf, der ihn zuverlässig macht, steht in docs/ki-workflow.md: erst Tests, dann Umsetzung, ein Modul nach dem anderen, Review durch einen Menschen. Was ein Agent zum Einstieg braucht und wie ein Auftrag aussieht, der ankommt: Mit Agenten arbeiten.

Vom Merge zum Release: zwei Wege

Ein Merge auf master erreicht Nutzer auf zwei verschiedenen Wegen, und nur einer davon braucht eine Versionsnummer.

Kontinuierlich, mit jedem passenden Merge. deploy-prototypes.yml baut bei Änderungen an Apps, Paketen, Handbuch oder Site die Web-App, die Site und das Storybook und veröffentlicht sie unter real-life-stack.de; dazu die OTA-Bundles, mit denen installierte Apps (F-Droid, Obtainium, iOS) ihren Web-Inhalt nachladen. publish-app-image.yml veröffentlicht bei Änderungen an Referenz-App, Paketen oder deploy/app/ das Container-Image der Edge-Instanz. Für all das wird keine Release-PR gemergt: Was auf master liegt, kann Nutzer noch am selben Tag erreichen.

Versioniert, über die Release-PR. release-please hält aus den Conventional Commits eine Release-PR offen. Wer sie mergt, erzeugt die Tags, und daraus werden die npm-Pakete (@real-life/*, für Apps außerhalb des Repos) und die nativen Artefakte der Referenz-App (APK für F-Droid, AAB für Play). Play bekommt keine OTA-Updates; eine Änderung erreicht Play erst mit diesem Weg. Ein Fix in einem Paket kaskadiert deshalb auf die App-Version, damit er auch dort ankommt. Der ganze Mechanismus, mit seinen zerbrechlichen Stellen, steht in docs/RELEASING.md.

Zuständigkeiten und Erwartungen

Feste Zeitbudgets, Meetingpflichten und persönliche Zusagen erfindet diese Seite nicht. Was ein Beitrag sein soll und wer ihn reviewt, wird beim Einstieg mit den Maintainern vereinbart; das persönliche Onboarding mit einer Ansprechperson ist das Prinzip, das das Team dafür beschlossen hat. Die Fragen, die neue Mitbauende stellen (Ziel, Stand, Entscheidungen, Zeit, Geld), bekommen eine eigene Seite mit ehrlichen Antworten.

Repository und Issues · Wie dieses Handbuch aktuell bleibt