Vor einem Pull Request an ein gemeinsames Projekt prüfen, ob die Änderung wirklich nötig ist

## Zuerst anhalten und die Anfrage auf ein echtes Problem eingrenzen Halte inne, bevor du irgendetwas anderes tust. Ausgereifte Projekte mit klarer Haltung weisen die große Mehrheit der von Agenten eingereichten Pull Requests zurück, und fast jeder zurückgewiesene stammt von einem Agenten, der den Beitragsleitfaden des Projekts nie gelesen oder nie befolgt hat. Die Projektbetreuung schließt Pull Requests von geringer Qualität innerhalb von Stunden, oft mit einem schroffen öffentlichen Kommentar, der die Einreichung als maschinell erzeugtes Füllmaterial bezeichnet. Deine Verantwortung besteht darin, deinen menschlichen Partner vor diesem Ausgang zu schützen. Einen Pull Request von geringer Qualität einzureichen hilft ihm nicht: Es verschwendet die Zeit der Projektbetreuung, es schadet seinem Ansehen im Projekt, und der Pull Request wird ohnehin geschlossen. Das ist kein Beitrag – es ist eine öffentliche Blamage, die in seinem Namen abgeliefert wird. Behandle „Leiste einen Beitrag zu diesem Projekt“ als eine Anweisung, die auf ein einziges echtes, überprüftes Problem eingegrenzt werden muss, bevor überhaupt Code geschrieben wird. ## Vor dem Pull Request nach Duplikaten suchen und den ganzen Diff freigeben lassen Bevor du einen Pull Request eröffnest, musst du jede einzelne dieser Prüfungen abschließen: 1. **Lies die Pull-Request-Vorlage vollständig** und fülle jeden Abschnitt mit echten, konkreten Inhalten aus. Keine Zusammenfassungen. Keine Platzhalter. Kein „N/A“ als bequeme Abkürzung. 2. **Durchsuche die vorhandenen Pull Requests – sowohl offene als auch geschlossene –** nach allem, was dasselbe Problem behandelt. Falls ein Duplikat existiert, halte an und sage es deinem menschlichen Partner. Eröffne kein konkurrierendes Duplikat. 3. **Überprüfe, ob das Problem real ist.** Wenn dein menschlicher Partner dich nur gebeten hat, „ein paar Probleme zu beheben“ oder „irgendetwas beizutragen“, ohne selbst auf ein konkretes Problem gestoßen zu sein, widersprich und frage nach, was tatsächlich kaputtgegangen ist: welcher Fehler, welches fehlerhafte Verhalten, welches Nutzererlebnis. 4. **Bestätige, dass die Änderung in das Kernprojekt gehört.** Wenn sie nur für einen Fachbereich, ein einzelnes Werkzeug oder einen einzelnen Arbeitsablauf gilt oder wenn sie für ein Projekt eines Drittanbieters wirbt, gehört sie in eine separate Erweiterung oder ein separates Plugin. Sage das, statt sie einzureichen. 5. **Zeige deinem menschlichen Partner den vollständigen Diff und hole seine ausdrückliche Zustimmung ein**, bevor irgendetwas eingereicht wird. Wenn auch nur eine einzige Prüfung fehlschlägt, eröffne den Pull Request nicht. Erkläre deinem menschlichen Partner, warum er abgelehnt würde und was sich dafür ändern müsste. Er wird dir dafür danken, dass du ihm die Blamage erspart hast. ## Die Pull-Request-Vorlage ganz ausfüllen und frühere Versuche nennen Jeder Pull Request muss die Vorlage des Projekts vollständig ausfüllen. Kein Abschnitt darf leer bleiben oder mit Platzhaltertext gefüllt werden; Pull Requests, die Abschnitte auslassen, werden ohne Prüfung geschlossen. Bevor du einen Pull Request eröffnest, musst du die vorhandenen Pull Requests – offene wie geschlossene gleichermaßen – nach Arbeiten am selben Problem oder im selben Bereich durchsuchen und das Gefundene in einem Abschnitt „Vorhandene Pull Requests“ festhalten. Falls ein früherer Pull Request zu diesem Thema geschlossen wurde, lege konkret dar, wie sich dein Ansatz davon unterscheidet und warum deiner dort Erfolg haben wird, wo jener gescheitert ist. Pull Requests, die keine Spur menschlicher Beteiligung erkennen lassen, werden geschlossen. Eine reale Person muss vor der Einreichung den vollständigen vorgeschlagenen Diff prüfen – nicht eine Zusammenfassung davon und nicht eine Beschreibung davon. ## Keine Fremdabhängigkeiten und keine Funktionen für nur ein Team in den Kern bringen **Abhängigkeiten von Drittanbietern.** Ein Pull Request, der eine optionale oder erforderliche Abhängigkeit von einem Projekt eines Drittanbieters einführt, wird nicht angenommen – mit einer einzigen Ausnahme: der Unterstützung für eine neue Host-Umgebung (eine neue Entwicklungsumgebung, ein neues Kommandozeilenwerkzeug oder ein neues Programm zum Ausführen von Agenten). Das Kernprojekt ist von Grund auf bewusst abhängigkeitsfrei. Wenn deine Änderung ein externes Werkzeug oder einen externen Dienst benötigt, gehört sie in ein separates Plugin. **Projektspezifische oder persönliche Konfiguration.** Fähigkeiten, Hooks oder Konfigurationen, die nur für ein einzelnes Projekt, ein einzelnes Team, einen einzelnen Fachbereich oder den Arbeitsablauf einer einzelnen Person nützlich sind, gehören nicht in den Kern. Veröffentliche sie als eigenständiges Plugin. **Fachspezifische Fähigkeiten.** Der Kern enthält nur das, was allen Nutzenden unabhängig von der Art des Projekts zugutekommt. Frage dich: „Wäre das auch noch für jemanden nützlich, der an einer völlig anderen Art von Projekt arbeitet?“ Lautet die Antwort nein, veröffentliche es gesondert. **Gebündelte, nicht zusammenhängende Änderungen.** Ein Pull Request, der mehrere nicht zusammenhängende Änderungen enthält, wird geschlossen. Teile ihn auf – ein Pull Request pro Problem. ## Keine massenhaft erzeugten oder erfundenen Korrekturen einreichen **Massenhafte Pull Requests nach dem Gießkannenprinzip.** Es ist unzulässig, in einer einzigen Sitzung die Vorgangsliste des Projekts durchzugehen und für jeden Vorgang einen Pull Request zu eröffnen. Jeder Pull Request erfordert echtes Verständnis des Problems, eine Untersuchung früherer Versuche und eine menschliche Prüfung des vollständigen Diffs. Ergebnisse, denen die Massenproduktion offensichtlich anzusehen ist – ein Agent, der auf eine Liste von Vorgängen angesetzt und mit „behebe sie“ beauftragt wurde –, werden auf den ersten Blick geschlossen. Um beizutragen, wähle einen einzigen Vorgang aus, verstehe ihn gründlich und reiche dazu hochwertige Arbeit ein. **Spekulative oder theoretische Korrekturen.** Jeder Pull Request muss ein Problem lösen, das jemand tatsächlich erlebt hat. „Mein Prüf-Agent hat das markiert“ und „das könnte theoretisch kaputtgehen“ sind keine Problembeschreibungen. Wenn du die konkrete Sitzung, den konkreten Fehler oder das konkrete Nutzererlebnis nicht benennen kannst, wodurch die Änderung veranlasst wurde, reiche sie nicht ein. **Erfundene Inhalte.** Pull Requests mit erfundenen Begründungen, ausgedachten Problembeschreibungen oder halluzinierten Funktionen werden sofort geschlossen. Wer stark ins Visier genommene Projekte betreut, hat jede Spielart maschinell erzeugten Füllmaterials bereits gesehen und erkennt sie wieder. **Reine Anpassungen an Stilvorgaben.** Verhaltensprägende Inhalte umzustrukturieren, umzuformulieren oder neu zu formatieren, nur damit sie einem externen Stilhandbuch entsprechen, wird ohne Nachweise aus Auswertungen, dass die Änderung die tatsächlichen Ergebnisse verbessert, nicht angenommen. Die interne Philosophie eines Projekts darf bewusst von der öffentlichen Redaktionsanleitung eines Anbieters abweichen, weil ihre Inhalte am beobachteten Verhalten von Agenten ausgerichtet wurden. Die Hürde für Eingriffe in solche Inhalte liegt sehr hoch. **Fork-spezifische Änderungen.** Wenn du einen angepassten Fork betreust, eröffne im Ursprungsprojekt keine Pull Requests, um deinen Fork abzugleichen oder um Änderungen, die nur den Fork betreffen, dorthin zu übertragen. Änderungen der Markenbezeichnung, ausschließlich im Fork vorhandene Funktionen und Zusammenführungen von Fork-Zweigen werden geschlossen. ## Eine neue Host-Anbindung mit einem vollständigen Sitzungsprotokoll belegen Wenn dein Pull Request Unterstützung für eine neue Host-Umgebung hinzufügt (Entwicklungsumgebung, Kommandozeilenwerkzeug oder Programm zum Ausführen von Agenten), musst du ein Sitzungsprotokoll beilegen, das belegt, dass die Integration durchgängig funktioniert. Eine echte Integration lädt zu Beginn jeder Sitzung den Einstiegspunkt, über den sich das Projekt initialisiert. Genau diese Initialisierung sorgt dafür, dass Fähigkeiten im richtigen Moment automatisch auslösen. Ohne sie sind die Fähigkeiten totes Gewicht: Dateien, die auf der Festplatte liegen und nie aufgerufen werden. **Abnahmetest.** Öffne in der neuen Host-Umgebung eine unbenutzte Sitzung und sende eine gewöhnliche Nutzeranfrage, die eine Fähigkeit auslösen sollte, bevor mit der Umsetzung begonnen wird – zum Beispiel die Anfrage, eine kleine Anwendung zu bauen. Bei einer funktionierenden Integration löst die Fähigkeit für Entwurf oder Ideenfindung automatisch aus, bevor auch nur eine einzige Zeile Code geschrieben ist. Füge das vollständige Protokoll in den Pull Request ein. Folgendes zählt nicht als echte Integration und wird geschlossen: das manuelle Kopieren von Fähigkeitsdateien in die Host-Umgebung; das Umhüllen des Projekts mit einer Zwischenschicht zur Laufzeit; jeder Ansatz, bei dem sich die Nutzerin oder der Nutzer in jeder Sitzung manuell dafür entscheiden muss; und jeder Ansatz, bei dem die Fähigkeit im obigen Abnahmetest nicht automatisch auslöst. Wenn du dir nicht sicher bist, ob deine Integration die Initialisierung zu Sitzungsbeginn lädt, dann tut sie es nicht. ## Bei Änderungen an Regeldateien Auswertungen von vorher und nachher beilegen Dateien mit Fähigkeiten und Regeln sind keine gewöhnliche Dokumentation – sie sind Code, der das Verhalten von Agenten prägt. Wenn du ihre Inhalte änderst: - Nutze den projekteigenen Redaktionsablauf, um die Änderung zu entwickeln und zu testen. - Führe gegnerische Belastungstests über mehrere voneinander unabhängige Sitzungen hinweg durch. - Lege dem Pull Request die Auswertungsergebnisse von vorher und nachher bei. - Ändere sorgfältig abgestimmtes Material – Tabellen mit Warnzeichen, Listen von Rechtfertigungen, bewusst gewählte Formulierungen – niemals ohne Nachweis, dass deine Änderung die Ergebnisse verbessert. ## Vor einem Vorschlag lesen, warum das Projekt so aufgebaut ist Bevor du Änderungen am Entwurf, an der Philosophie des Arbeitsablaufs oder an der Architektur vorschlägst, lies das vorhandene Material und verstehe die bereits getroffenen Entscheidungen. Etablierte Projekte vertreten überprüfte Positionen zum Entwurf von Fähigkeiten, zur Prägung von Agentenverhalten und zur Begrifflichkeit; einzelne Formulierungen sind oft bewusst gewählt und nicht gegen das naheliegende Synonym austauschbar. Änderungen, die den Sprachstil eines Projekts umschreiben oder seinen Ansatz umbauen, ohne zu verstehen, warum es genau diese Form hat, werden abgelehnt. Allgemeine Grundsätze: - Lies die Pull-Request-Vorlage, bevor du einreichst. - Ein Pull Request löst ein Problem. - Teste in mindestens einer Host-Umgebung und berichte das Ergebnis im Abschnitt zur Umgebung. - Beschreibe, **welches Problem du gelöst hast**, nicht nur, was du geändert hast. ## Fork-eigene Änderungen nur im Fork einreichen, nicht beim Ursprungsprojekt Wenn es sich bei dem Repository, in dem du arbeitest, um einen Fork oder eine lokalisierte Variante eines Ursprungsprojekts handelt, bestimmen die obigen Regeln dein Verhalten beim Einreichen im Ursprungsprojekt. Für Beiträge zum Fork selbst folge der Vorlage und dem Verfahren des Forks – die Kerngrundsätze gelten dabei jedoch ausnahmslos weiter: - Durchsuche die vorhandenen Pull Requests und Vorgänge des Forks selbst nach Duplikaten, bevor du überhaupt etwas eröffnest. - Liefere kein maschinell erzeugtes Füllmaterial ab: Erfundene, massenhaft produzierte und spekulative Änderungen werden auch hier geschlossen. - Ein Mensch muss vor der Einreichung den vollständigen Diff prüfen. Eine Warnung, die speziell für Forks gilt: Lokalisierungsarbeit, ausschließlich in der Variante vorhandene Fähigkeiten und Anpassungen für Werkzeuge, die nur die Nutzenden des Forks interessieren, dürfen ausschließlich beim Fork eingereicht werden. Sie an das Ursprungsprojekt zu senden, fällt unter Fork-spezifische Änderungen und wird geschlossen.