xz-dev/downstream-fork-maintain-skill

Wartung des Downstream-Forks

Überblick

Der Zweck der Pflege eines Downstream-Forks besteht nicht darin, ihn allmählich vom Upstream abdriften zu lassen und zu einem unabhängig evolvierenden Hard Fork zu machen. Es geht darum, kontinuierlich einen Satz von Patches zu erhalten, die nutzbar, baubar und testbar bleiben.

Der Downstream folgt dem Upstream, während er den Benutzern umgehend Code und Artefakte mit diesen Funktionen und Fehlerbehebungen zur Verfügung stellt, wenn PRs noch nicht gemergt wurden, Upstream-Maintainer beschäftigt sind oder ein Patch nischenhaft, aber dringend ist. Es ist kein statisches Patch-Archiv, sondern ein Verteilungskanal, in dem Patches tatsächlich ausgeführt und validiert werden.

Ein nutzbares integriertes Ergebnis ermöglicht es auch mehr Menschen, Upstream-PRs, Downstream-Patches und eigene Änderungen frei zu testen. Während sich der Upstream weiterentwickelt, reduziert das kontinuierliche Bauen, Testen und Überprüfen der Patches das Risiko, dass PRs nach einem Zurückfallen hinter den Upstream verrotten, deckt Probleme früher auf und hilft, dass Änderungen letztlich in den Upstream zurückfließen.

Kernziele

• Verhindern, dass der Downstream-Fork zu einem Hard Fork wird, der vom Upstream getrennt bleibt.
• Kontinuierlich dem Upstream folgen, anstatt nur einen statischen Branch von einem bestimmten Zeitpunkt zu bewahren.
• Jeden Patch unabhängig baubar, testbar, überprüfbar und für die Einreichung oder laufende PR-Pflege geeignet halten.
• Direkt nutzbaren Code und Artefakte über den Haupt- oder Release-Branch bereitstellen.
• Benutzern ermöglichen, PRs, Patches und eigene Änderungen gegen ein echtes integriertes Ergebnis zu testen.
• Konflikte zwischen Patches und dem Upstream frühzeitig erkennen, PRs mergebar halten und Patches dabei helfen, in den Upstream zurückzufließen.

Branch-Modell

Das Repository bestimmt die tatsächlichen Branchnamen. Gehen Sie nicht von einem Standard-Branch, Remote-Namen oder einer Hosting-Plattform aus.

Upstream-Main-Branch

Der Upstream-Main-Branch ist der Ausgangspunkt für jeden Neubau. Holen Sie seinen neuesten Stand vor der Synchronisation ein und verwenden Sie einen bestimmten Upstream-Commit als Basis für den aktuellen Build.

Der Downstream-Main- oder Release-Branch darf nicht zur neuen Basis für Patches werden. Ein Patch sollte immer klarstellen, was er relativ zum Upstream ändert.

Patch-Branches

Pflegen Sie jeden unabhängigen Patch auf einem eigenen Branch und halten Sie ihn an normale PR-Standards:

• Halten Sie den Umfang fokussiert und die Commits und Erklärungen klar.
• Fügen Sie ausreichend Tests hinzu, um das Verhalten zu demonstrieren.
• Machen Sie ihn auf dem aktuellen Upstream unabhängig baubar und überprüfbar.
• Deklarieren Sie nur notwendige Abhängigkeiten und vermeiden Sie die Bindung an andere Downstream-Patches.
• Machen Sie ihn für die direkte Einreichung als Upstream-PR oder für die laufende Pflege eines bestehenden PRs geeignet.
• Im Allgemeinen sollte ein Patch-Branch keine Release-Dateien ändern, die zentral von Upstream-Maintainern verwaltet werden, wie z.B. CHANGELOG. Notwendige Dokumentationsänderungen sollten auf Code-Kommentare, API-Dokumentation und Implementierungsnotizen beschränkt sein, die direkt mit diesem Patch zusammenhängen. Pflegen Sie die Downstream-Patch-Liste und Release-Notizen zentral auf dem Wartungsbranch.

Der Patch-Branch ist die langfristige Quelle der Wahrheit für diesen Patch. Ein Integrations-Commit auf dem Release-Branch ist nicht die einzige Kopie des Patches und darf keine temporären Korrekturen enthalten, die nur in der Release-Historie existieren.

Temporäre Kompatibilitäts-Patch-Branches

Wenn mehrere Patches unabhängig voneinander angewendet werden, aber in Kombination einen Build-, Test- oder Verhaltenskonflikt verursachen, der zu keinem einzelnen PR-Branch gehört, pflegen Sie einen Kompatibilitäts-Patch auf einem tmp/patch/<name>-Branch.

Ein solcher Branch adressiert nur das Downstream-Kompatibilitätsproblem für eine bestimmte Patch-Kombination. Erzwingen Sie die Fehlerbehebung nicht in einem der unabhängigen PR-Branches und lassen Sie ihn nicht zu einem neuen langfristigen Feature-Branch werden. Er muss angeben, von welchen Patches er abhängt, wo er in der Reihenfolge steht, welches kombinierte Verhalten er validiert und wann er ausgemustert werden kann.

Fügen Sie in der Synchronisations-Orchestrierung auf dem ci-Branch tmp/patch/<name> direkt nach den Patches ein, von denen er abhängt. Wenn ein früherer Git-Merge bereits ungelöste textuelle Konflikte erzeugt hat, kann ein späterer Kompatibilitätsbranch diesen Konflikt nicht überbrücken. In diesem Fall muss die ci-Orchestrierung die entsprechende Kompatibilitätsbehandlung explizit an dem Schritt anwenden, an dem der Konflikt auftritt, bevor der Neubau fortgesetzt wird; das bloße Anhängen des Branches an das Ende der Liste ist nicht ausreichend.

Der ci-Wartungsbranch

Wenn der Fork Automatisierung wie GitHub Actions tragen muss, pflegen Sie einen separaten ci-Branch. Wenn das Repository bereits einen entsprechenden Branch hat, behalten Sie seinen Namen bei. Dieser Branch ist das Release-Overlay des Downstream-Forks und ist verantwortlich für:

• Downstream-spezifische CI/CD, Paketierung, Releases und Repository-Konfiguration.
• Automatisches Holen des Upstreams, Integrieren von Patches in der richtigen Reihenfolge, Neuerstellen des Release-Branches und sicheres Pushen.
• Zusätzliche Downstream-Einzelpatch-Tests und Multi-Patch-Integrationstests.
• Das Downstream-README, die Patch-Liste, Release-Notizen und alle Downstream-spezifischen Wartungsanweisungen.
• Die festgelegte Integrationsreihenfolge aktivierter regulärer Patches und tmp/patch/<name>-Branches.

Wenn der Benutzer oder Downstream-Fork Wartungsanforderungen hat, die über diesen allgemeinen Workflow hinausgehen, halten Sie diese in einer Downstream-eigenen MAINTAIN.md auf dem ci-Branch fest. Sie sollte angeben, wie dieser spezielle Fork gepflegt werden muss, und alle speziellen Regeln dokumentieren, die zukünftige Maintainer und Automatisierung befolgen müssen. Behandeln Sie sie als Repository-spezifische Anleitung: Lesen Sie sie, bevor Sie Patch-Branches, Sync-Orchestrierung oder Release-Historie ändern, und halten Sie sie auf dem neuesten Stand, wenn sich diese Anforderungen ändern.

Wenn die speziellen Wartungsregeln sonst übersehen werden könnten, fügen Sie einen kurzen Hinweis im README.md des ci-Branches hinzu, der auf MAINTAIN.md verweist. Halten Sie die detaillierten Regeln in MAINTAIN.md, anstatt sie im README zu duplizieren.

Der ci-Branch kann zentral Downstream-Release-Automatisierung tragen, mischen Sie jedoch keine Produktverhaltens-Patches hinein. Laufzeitänderungen sollten auf Branches bleiben, die für unabhängiges Bauen, Testen und Upstream-PR-Einreichung geeignet sind.

Diese Fähigkeit enthält die GitHub Actions-Datei, die in der aktuellen Praxis verwendet wird: ref/upstream-sync.yml. Wenn eine automatische GitHub-Synchronisation benötigt wird, kopieren Sie sie als Ausgangspunkt für .github/workflows/upstream-sync.yml und passen Sie dann die Upstream-Adresse, den Standard-/Release-Branch, die ci- und Patch-Listen, die tmp/patch/<name>-Reihenfolge, den Sync-Zeitplan, die Downstream-eigenen Dateien, Geheimnisse und Prüfungen für das Ziel-Repository an. Die Datei behält projektspezifische Konfiguration aus ihrem ursprünglichen Projekt bei und darf nicht ohne Überprüfung aktiviert werden.

Wenn Sie den schedule konfigurieren, fragen Sie zuerst den Benutzer, zu welchen Stunden jeden Tag die Synchronisation laufen soll. GitHub Cron verwendet standardmäßig UTC, es sei denn, der Workflow legt explizit eine unterstützte timezone fest. Planen Sie Jobs nicht auf Minute 0 der Stunde: GitHubs offizielle Dokumentation besagt, dass die Last zu Beginn jeder Stunde hoch ist, sodass geplante Jobs bei ausreichend hoher Last verzögert oder sogar ausgelassen werden können. Um häufige Fünf-Minuten-Marken weiter zu vermeiden, verwenden Sie kein Vielfaches von 5, wie 10, 15, 20, 30, 40 oder 45. Wählen Sie zufällig eine Minute von 1–59, die kein Vielfaches von 5 ist, und schreiben Sie sie als festen Wert in den Workflow, z.B. durch Ausführen von python -c 'import secrets; print(secrets.choice([m for m in range(1, 60) if m % 5]))'. Hier bezieht sich „zufällig“ nur auf die Generierung der Konfiguration; lassen Sie den Workflow nicht bei jeder Ausführung auf eine dynamische zufällige Verzögerung warten.

Haupt- oder Release-Branch

Der Haupt- oder Release-Branch beginnt beim neuesten Upstream und integriert den Wartungsbranch und die erforderlichen Patch-Branches in einer festgelegten Reihenfolge. Er stellt den vollständigen Code, Builds, Tests und Release-Artefakte bereit.

Dieser Branch repräsentiert nur das aktuelle integrierte Downstream-Ergebnis. Er ist nicht die langfristige Wartungsquelle für einen Patch. Ein Problem kann hier zuerst reproduziert und analysiert werden, aber die Korrektur muss zum zugehörigen Patch- oder Wartungsbranch zurückkehren, wonach das integrierte Ergebnis neu generiert werden muss.

In der Release-Historie sollte jeder Patch als ein klarer, zählbarer Integrations-Commit erscheinen, der sowohl die Anzahl der Downstream-Patches als auch die Anzahl der Commits, um die der Fork hinter dem Upstream zurückliegt, sichtbar macht.

Workflow

1. Inspizieren des aktuellen Zustands

Lesen Sie vor dem Start die eigenen Wartungs- und Beitragsanweisungen des Repositorys, einschließlich der vorhandenen Downstream-MAINTAIN.md und aller README-Hinweise, die darauf verweisen. Inspizieren Sie den Arbeitsbaum, Remotes, aktuellen Branch, Upstream-Beziehungen und den bestehenden Sync- und Release-Prozess. Bewahren Sie nicht festgeschriebene Benutzerarbeit oder arbeiten Sie darum herum; bereinigen Sie sie nicht und überschreiben Sie sie nicht ohne Erlaubnis.

2. Prüfen von Upstream-Issues und Pull-Requests vor der Codierung

Bevor Sie eine neue Anfrage implementieren oder Code schreiben, durchsuchen Sie den Upstream-Issue-Tracker und die Pull-Requests nach verwandten Diskussionen oder Implementierungen. Überprüfen Sie offene und geschlossene Issues sowie offene, Entwurfs-, geschlossene und gemergte PRs; suchen Sie nicht nur nach der exakten Formulierung der Anfrage, sondern auch nach relevanten Komponentennamen, Fehlermeldungen und sinnvollen Synonymen. Folgen Sie verlinkten Issues, Reviews, Commits und Ersatz-PRs weit genug, um den aktuellen Status zu ermitteln.

Verwenden Sie das Ergebnis, um die nächste Aktion auszuwählen:

• Wenn der Upstream die Anforderung bereits implementiert, überprüfen Sie die zutreffende Version und das Verhalten, bevor Sie entscheiden, ob eine Downstream-Änderung noch erforderlich ist.
• Wenn ein aktives Issue oder PR dies abdeckt, bevorzugen Sie es, zu dieser Arbeit beizutragen, sie zu testen, zu aktualisieren oder vorübergehend zu übernehmen, anstatt ein unwissentliches Duplikat zu erstellen.
• Wenn ein früherer Ansatz abgelehnt, zurückgesetzt oder ersetzt wurde, verstehen Sie den genannten Grund, bevor Sie eine neue Implementierung vorschlagen.
• Dokumentieren Sie die relevanten Upstream-Links und die Schlussfolgerung im Arbeitsplan, in den Patch-Notizen oder in der PR-Beschreibung, damit die Entscheidung überprüfbar bleibt.

Wenn verwandte Upstream-Issues oder PRs existieren, fahren Sie nicht direkt mit der Implementierung fort. Stellen Sie zunächst ihren tatsächlichen Status, Umfang, Entscheidungen, ungelöste Anliegen, Review-Feedback, Implementierungsstand und Beziehung zur Benutzeranfrage fest. Fassen Sie dann die relevanten Upstream-Informationen für den Benutzer zusammen, anstatt eine rohe Liste von Links weiterzuleiten. Erklären Sie klar, was gelernt wurde, wie es die aktuellen Annahmen und den Plan beeinflusst und welche Teile der ursprünglichen Anfrage weiterhin notwendig sind.

Wenn diese Untersuchung ein neues Ergebnis liefert, das den Umfang, den Ansatz, die Priorität, die Zuständigkeit, die Kompatibilitätsstrategie oder die Notwendigkeit der Arbeit ändern könnte, fragen Sie den Benutzer explizit, ob der Plan geändert werden sollte. Halten Sie die Implementierung an, bis der Benutzer bestätigt, ob der Plan beibehalten oder überarbeitet werden soll. Interpretieren Sie die Anfrage nicht stillschweigend auf der Grundlage der Upstream-Diskussion neu.

Beginnen Sie nicht mit der Implementierung, nur weil eine Suche mit einem exakten Begriff kein Ergebnis liefert. Führen Sie zuerst eine sinnvolle Suche durch; wenn keine relevante Diskussion oder Implementierung gefunden wird, geben Sie dieses Ergebnis an und fahren Sie fort.

3. Reproduzieren auf dem vollständigen integrierten Ergebnis

Reproduzieren Sie das Problem zuerst auf dem aktuellen Haupt- oder Release-Branch, um zu bestätigen, wie es in der Patch-Kombination auftritt, die Benutzer tatsächlich ausführen.

Unterscheiden Sie während der Analyse zwischen:

• Einem Problem im Upstream selbst.
• Einem Problem in einem unabhängigen Patch.
• Einem Integrationsproblem zwischen Patches; wenn es zu keinem einzelnen PR gehört, platzieren Sie es in tmp/patch/<name>.
• Einem Problem in CI, Paketierung, Synchronisation oder Downstream-Dokumentation.

4. Lokalisieren und Korrigieren des zuständigen Branches

Finden Sie den Patch-Branch, der für das Verhalten verantwortlich ist, und führen Sie die Fehlerbehebung und Tests auf diesem Branch durch. Wenn das Problem die Kompatibilität zwischen mehreren Patches betrifft, erstellen oder aktualisieren Sie tmp/patch/<name>. Wenn es die Release-Automatisierung oder andere Downstream-Wartungsarbeit betrifft, modifizieren Sie den ci-Branch.

Führen Sie eine Konfliktbehebung oder Produktkorrektur nicht nur auf dem Haupt- oder Release-Branch durch. Sie wäre beim nächsten Neubau vom Upstream verloren und würde verhindern, dass der Patch unabhängig überprüft werden kann.

5. Halten Sie den Patch unabhängig nutzbar

Aktualisieren Sie den Patch gemäß den Repository-Konventionen auf den neuesten Upstream, lösen Sie Konflikte auf dem Patch-Branch und führen Sie die für diesen Patch erforderlichen Builds und Tests durch.

Bestätigen Sie, dass er nicht auf versteckte Änderungen im Release-Branch angewiesen ist und weiterhin als eigenständiger PR erklärt, überprüft und eingereicht werden kann. Wenn bereits ein Upstream-PR existiert, aktualisieren Sie ihn ebenfalls und pflegen Sie ihn als Reaktion auf Upstream-Feedback weiter.

6. Neuerstellen des Haupt- oder Release-Branches

Holen Sie den neuesten Upstream erneut, erstellen Sie einen sauberen Kandidaten-Branch von einem bestimmten Upstream-Head und integrieren Sie dann das Release-Overlay, die regulären Patches und die erforderlichen tmp/patch/<name>-Branches in der vom ci-Branch deklarierten festgelegten Reihenfolge.

Jeder reguläre Patch und temporäre Kompatibilitätspatch sollte seinen eigenen klaren Integrations-Commit in der Release-Historie erzeugen. Ein Repository kann Squash-Merge oder die vom Projekt festgelegte äquivalente Methode verwenden, aber das Ergebnis sollte leicht zu überprüfen und zu zählen sein.

7. Validieren des nutzbaren Ergebnisses

Führen Sie die erforderlichen Prüfungen des Repositorys gegen die vollständige Kandidatenversion durch, die mindestens abdecken:

• Fokussierte Tests für jeden Patch selbst.
• Integriertes Verhalten nach Kombination mehrerer Patches.
• Ob CI, Paketierung und Downstream-Dokumentation von den richtigen Branches stammen.
• Ob der Code oder die Artefakte, die Benutzer tatsächlich erhalten, dem validierten Commit entsprechen.

Aktualisieren Sie den entfernten Haupt- oder Release-Branch erst, nachdem sowohl der Kandidaten-Code als auch die Artefakte alle erforderlichen Validierungen bestanden haben.

Automatische Synchronisation

Der Zweck der automatischen Synchronisation besteht darin, regelmäßig ein nutzbares Downstream-Release-Ergebnis von einem neuen Upstream-Head zu regenerieren, nicht darin, Korrekturen auf einem alten Release-Branch anzuhäufen.

Der Synchronisationsprozess sollte:

1. Die akzeptierten Concurrency-Kontrollen des Repositorys verwenden, um zu verhindern, dass zwei Sync- oder Release-Prozesse denselben Branch gleichzeitig aktualisieren.
2. Den neuesten Upstream, den ci-Branch, alle aktivierten regulären Patches und alle tmp/patch/<name>-Branches holen.
3. Einen sauberen Kandidaten-Branch vom explizit ausgewählten Upstream-Commit für diesen Lauf erstellen.
4. Das Downstream-Release-Overlay, die regulären Patches und die temporären Kompatibilitäts-Patches in der festgelegten Reihenfolge integrieren.