Eine mehrsprachige Ressourcenliste aus Datendateien pflegen, ohne Seiten von Hand zu ändern

## Verstehen, dass die Listenseiten aus Datendateien erzeugt werden Du pflegst eine kuratierte Wissensdatenbank, deren für Menschen bestimmte Ausgaben **generiert** und nicht verfasst werden. Verstehe diese Trennung, bevor du irgendetwas änderst: - Die **maßgebliche Datenquelle** ist eine Reihe strukturierter Datendateien: ein Kategorie-/Abschnittsbaum (der Anker und das Inhaltsverzeichnis festlegt) sowie eine Eintragsdatei pro Abschnitt. - **Generierte Artefakte** – die für Menschen lesbaren Auflistungsdokumente (eines pro unterstützter Sprache) sowie jeder maschinenlesbare Index – werden aus diesen Daten durch ein Generator-Skript erzeugt. Sie sind wegwerfbar und werden bei Bedarf neu erstellt. - Dieselben zugrunde liegenden Daten können auch eine Laufzeit-Abfrageschnittstelle für automatisierte Agenten speisen, sodass die Datenqualität Abnehmer hat, die über die gerenderten Dokumente hinausgehen. Hier gibt es in der Regel keine Anwendungslaufzeitumgebung, keinen Build und keine Testsuite. Jede Änderung fällt in eine von drei Kategorien: strukturierte Daten, Werkzeug-Skripte oder Dokumentation. Behalte dieses Denkmodell bei – es verhindert den häufigsten und schädlichsten Fehler: das Bearbeiten einer Ausgabe, die ohnehin überschrieben wird. ## Daten ändern und Seiten neu erzeugen, statt sie zu bearbeiten - **Bearbeite niemals ein generiertes Ausgabedokument direkt.** Änderungen gehen bei der nächsten Neugenerierung verloren. Um zu ändern, was ein Leser sieht, ändere die zugrunde liegenden Daten. - Um einen Eintrag hinzuzufügen oder zu ändern, bearbeite die Eintragsdatei des betreffenden Abschnitts. - Um einen neuen Abschnitt hinzuzufügen, bearbeite zuerst die Kategorie-/Abschnittsbaum-Datei und erstelle anschließend die passende Eintragsdatei. Führe danach das Anker-Prüfwerkzeug aus, um sicherzustellen, dass kein extern referenzierter Anker verloren gegangen ist. - Führe nach jeder Datenänderung den Generator lokal aus, um alle generierten Dateien zu aktualisieren, bevor du committest. Die kontinuierliche Integration weist einen Arbeitsbaum zurück, der von frisch generierter Ausgabe abweicht – generiere also neu, statt zu raten. - Bearbeite den maschinenlesbaren Index nicht von Hand; er wird vollständig vom Generator neu erzeugt. ## Felder jedes Eintrags ausfüllen und eine Beschreibung in einem Satz schreiben Jeder Eintrag ist ein strukturierter Datensatz mit Pflichtfeldern (eine stabile eindeutige ID, URL, Titel, Kategorie, Typ, Schwierigkeitsgrad, Sprachauswahl, Hinzufügedatum, Status) sowie optionalen Feldern, die automatisiert befüllt werden (Archiv-URL, Zeitstempel der letzten Prüfung, Inhalts-Fingerabdruck). Halte dich an die kontrollierten Vokabulare für Typ, Schwierigkeitsgrad, Sprache und Status – erfinde keine Werte. Behandle die Freitextbeschreibung, die einem Eintrag beiliegt, als **öffentlich sichtbaren, für Dritte lesbaren Text**: - **Enthalte** einen einzelnen sachlichen Satz, der beschreibt, worum es sich bei der Ressource handelt, optional gefolgt von einer Autorennennung. - **Lasse** alles Interne **weg**: Verweise auf dieses Projekt, Issue- oder Änderungsanfrage-Nummern, Formulierungen wie „ursprünglich vorgeschlagen von" oder sonstige historische Metadaten. Der Versionsverlauf bewahrt die Zuschreibung bereits; ein außenstehender Leser darf keine Verbindung zwischen dem Eintrag und diesem Repository erkennen können. - Lasse maschinell migrierte Werte unverändert, sofern das Original nicht falsch oder veraltet ist. - Schließe einen Eintrag nur dann von der externen Archivierung aus, wenn der ursprüngliche Autor dies ausdrücklich verlangt hat (kostenpflichtige Inhalte, Löschanfragen). ## Linknamen der Abschnitte nicht ändern, damit externe Links funktionieren Sowohl externe Seiten als auch das interne Inhaltsverzeichnis verweisen auf benannte Anker. Wird ein bestehender Anker umbenannt oder entfernt, bricht stillschweigend jeder eingehende Link, der auf ihn zielt. - **Benenne einen bestehenden Anker niemals um und entferne ihn nicht.** Füge stattdessen neue Anker für neue Abschnitte hinzu. - Eine Prüfung der kontinuierlichen Integration vergleicht die aktuelle Ankermenge mit der Ausgangsbasis und lässt den Build fehlschlagen, wenn ein Basis-Anker fehlt. Behandle diese Prüfung als feste Hürde, nicht als Empfehlung. - Da der Generator Einträge deterministisch sortiert (nach Hinzufügedatum, dann Titel), darfst du Einträge niemals massenhaft von Hand umsortieren. Um einen Eintrag weiter nach vorne in der Liste zu verschieben, ändere seinen Hinzufügedatum-Wert, statt die Datensätze neu anzuordnen. ## Code und Notizen in einer Hauptsprache schreiben und Sprachausgaben je Eintrag wählen Projekteigene Inhalte werden in einer Hauptsprache verfasst. Mehrere Sprachen kommen nur dort vor, wo Mehrsprachigkeit dem Artefakt von Natur aus innewohnt: übersetzte Ausgabedokumente, lokalisierte Überschreibungen von Abschnittstiteln, eintragsspezifische Titel, die die Originalsprache der Ressource bewahren, sowie Auslösephrasen, die bei Eingaben in einer anderen als der Hauptsprache greifen sollen. Alles andere – Code, Kommentare, Feldnamen, Vorlagen, Pipeline-Ausgaben, Beschriftungen, Commit-Nachrichten – bleibt in der Hauptsprache. Ein einzelner Eintrag kann in mehreren Sprachausgaben erscheinen, gesteuert über seine Sprachauswahl: - Neuer Eintrag ohne Sprachhinweis → liste ihn nur in der Hauptsprache und frage den Beitragenden, ob er ihn auch in weiteren Ausgaben haben möchte. - Regionsspezifische Ressource → kennzeichne sie nur mit dieser einen Region. - Wirklich kulturübergreifende, kanonische Ressource → kennzeichne sie über die betreffenden Sprachen hinweg, oder verwende den Platzhalter sparsam. - Übersetze oder spiegele einen Eintrag niemals zwangsweise über die Ausgaben hinweg, nur damit die Strukturen übereinstimmen. Jede Ausgabe darf Einträge enthalten, die die anderen nicht haben. ## Beiträge übernehmen, ohne die Nennung der Beitragenden zu verlieren Eingehende Anfragen kommen in zwei Formen und müssen so übertragen werden, dass die Anerkennung nie verloren geht: - **Strukturierter Vorschlag (kein Branch):** Übertrage den Eintrag direkt in das Datenmodell, generiere neu, führe die Prüfwerkzeuge aus und committe mit einem Co-Autor-Vermerk, der den Einreichenden nennt – dieser Vermerk ist seine einzige Anerkennung. - **Direkte Änderungsanfrage (Beitragender hat Dateien auf einem eigenen Branch bearbeitet):** Übertrage die Arbeit *auf seinem Branch*, damit seine Änderung mit vollständiger Zuschreibung gemergt wird. Leite eine direkte Änderung eines Beitragenden niemals über einen automatisierten Assistenten, der eine eigene, konkurrierende Anfrage eröffnet und die des Beitragenden schließt – das zerstört seine Merge-Anerkennung. Ein automatisierter Coding-Assistent darf nur als **asynchrone Ausweichlösung für strukturierte Vorschläge** dienen, wenn der Maintainer nicht verfügbar ist und die Warteschlange weiterlaufen muss. Das ist nicht der Standardweg; ein Mensch prüft das Ergebnis weiterhin vor dem Merge. Der Assistent erspart Tipparbeit, nicht die Beurteilung. ## Jede Änderung automatisch prüfen und den Prüf-Bot nur beraten lassen Bei jeder Änderung, die Daten oder Generator-Skripte betrifft, sollte die Pipeline: 1. Schema-Prüfung und Anker-Prüfung ausführen. 2. Den Generator erneut ausführen und warnen, falls der Arbeitsbaum von frisch generierter Ausgabe abweicht (ein Zeichen dafür, dass der Beitragende die Neugenerierung vergessen hat). 3. Einen automatisierten Begutachtungs-Bot aufrufen, der jeden neuen Eintrag anhand eines veröffentlichten Bewertungsrasters beurteilt, einen strukturierten Kommentar hinterlässt und beratende Kennzeichnungen vergibt. Gestalte den Begutachtungs-Bot zurückhaltend: Erkenne die Sprache des Beitragenden deterministisch (nicht über das Modell) und übergib sie als Vorgabe; schlägt der Modellaufruf fehl, weiche auf deterministische Erreichbarkeits- und Formatprüfungen unter einer eigenen Kennzeichnung „review-failed" aus. **Der Bot merged nie automatisch und lehnt nie automatisch ab** – er berät, Menschen entscheiden. ## Seiten nie von Hand ändern und bei nicht geregelten Änderungen nachfragen Nicht: - Generierte Ausgabedokumente oder den maschinenlesbaren Index von Hand bearbeiten. - Bestehende Anker umbenennen oder entfernen. - In Vorlagen Markup einführen, das über die vom Projekt erlaubte Tag-Positivliste hinausgeht. - Bestehende Einträge massenhaft umsortieren, statt die Sortierschlüssel anzupassen. - Beitragsrichtlinien, Verhaltenskodex oder Workflow-Definitionen bearbeiten, sofern nicht ausdrücklich verlangt. - Commits erstellen oder pushen, sofern nicht ausdrücklich verlangt. Wenn eine Änderung in einen Bereich vorstößt, den diese Regeln nicht abdecken – eine neue Sprachausgabe, ein neues Schemafeld, eine neue Abschnittstaxonomie –, halte an und frage nach, statt zu improvisieren. Orientiere dich am Geist des Beitragsleitfadens und des Bewertungsrasters, und hole im Zweifel die Bestätigung eines Menschen ein, bevor du handelst.