shagghiesuperstar/hermes-skills

Batch-Landing von Dokumentations-PRs

Übersicht

Viele kleine Dokumentations-Pull-Requests lassen sich leichter als einer überprüfen. Diese Prozedur kopiert die Dateien aus mehreren überprüften, dokumentationsbezogenen Pull Requests in einen neuen Entwurf-PR, ein Commit pro Quelle. Die Dateiinhalte werden exakt kopiert, ohne Bearbeitung. Die Quell-PRs bleiben unverändert. Ein Reviewer führt dann den einen Batch-PR zusammen, und die Quell-PRs schließen sich über ihren eigenen Status, nicht durch eine Aktion in dieser Prozedur.

Wann verwenden

• Mehrere offene Dokumentations-Pull-Requests haben die Überprüfung bestanden und betreffen jeweils nur Dokumentationspfade.
• Ein Reviewer wünscht einen Pull Request, der sie gemeinsam führt.

Nicht zu verwenden für Code, Konfiguration oder für Quell-PRs, die die Überprüfung nicht bestanden haben.

Funktionen

• Ein temporärer Arbeitsbaum, sodass der funktionierende Checkout nicht berührt wird.
• Ein Live-Snapshot des Zustands jedes Quell-PRs: Basis, Head und Dateiliste, geprüft gegen den abgerufenen Head-Commit.
• Überspringungsregeln für Pull Requests, die geschlossen sind, Pfade außerhalb des Dokumentationsordners betreffen, mit main kollidieren oder mit einem anderen offenen PR kollidieren.
• Ein Commit pro eingespielter Quelle, mit Assertions, die den Durchlauf bei einer fehlerhaften Quelle stoppen.
• Prüfungen auf die geänderten Pfade vor dem Push und ein Verifikationsblock, der jede Datei mit ihrem Quell-Head vergleicht.

Vorteile

• Eine fehlerhafte Quelle stoppt den Durchlauf, anstatt teilweise einzuspielen.
• Der Inhalt jeder eingespielten Datei wird als identisch mit der Quelle nachgewiesen.
• Übersprungene PRs werden mit Grund aufgelistet, sodass nichts stillschweigend wegfällt.
• Der Batch-PR wird als Entwurf geöffnet, sodass der Reviewer die endgültige Entscheidung trifft.

Prozedur

1. Arbeiten in einem temporären Arbeitsbaum. Den Hauptbranch und die Quell-PR-Heads abrufen, dann einen neuen Branch von main in einem temporären Ordner erstellen:

   git fetch origin main '+refs/pull/*/head:refs/remotes/origin/pr/*'
   git worktree add -b <batch-branch> <scratch-dir>/wt origin/main
   

   Wenn ein HTTPS-Fetch oder -Push bei der Authentifizierung fehlschlägt, den betreffenden Befehl mit dem Credential-Helper des Code-Host-CLI ausführen, z. B. -c credential.helper= -c 'credential.helper=!gh auth git-credential'. Die gespeicherte Konfiguration nicht ändern und kein Token ausgeben.

2. Den Live-Zustand einmal erfassen. Für jeden Quell-PR seinen Status, Draft-Flag, Basisbranch, Head-Commit und Dateiliste auslesen. Auch die offenen Pull Requests für Kollisionsprüfungen auflisten. Bestätigen, dass der Head-Commit jedes Quell-PRs mit dem abgerufenen refs/remotes/origin/pr/<n>-Commit übereinstimmt.

3. Entscheiden überspringen oder einspielen, in numerischer Reihenfolge. Einen PR überspringen und den Grund erfassen, wenn eines der folgenden Kriterien zutrifft:

   • Er ist nicht offen.
   • Einer seiner Pfade liegt außerhalb des Dokumentationsordners.
   • Einer seiner Pfade existiert bereits auf main. Bei einem bereits auf main vorhandenen Pfad die Blobs vergleichen. Identischer Inhalt bedeutet, dass er früher eingespielt wurde. Unterschiedlicher Inhalt bedeutet, dass ein Rebase erforderlich ist.
   • Ein anderer offener Pull Request ändert einen seiner Pfade.

4. Jeden PR als einen Commit einspielen. Für jeden eingespielten PR seine Dateien aus dem Head-Commit auschecken und mit einer Nachricht committen, die den PR benennt. Dies in einer Schleife ausführen, die bestätigt, dass der PR offen ist, der Head übereinstimmt, die Pfade im Dokumentationsordner liegen und keiner von ihnen auf main ist. Ein fehlgeschlagener Assert stoppt den Durchlauf.

   git checkout <head-commit> -- <paths>
   git commit -m "docs: land #<n>"
   

5. Die Änderungen vor dem Push prüfen. Geänderte Dateien außerhalb des Dokumentationsordners müssen null sein. Die Gesamtzahl der geänderten Dateien muss der Summe der Pfadzahlen pro PR entsprechen.

6. Den Verifikationsblock erstellen. Für jeden PR und jeden seiner Pfade den Blob auf dem HEAD des Batch-Branches mit dem Blob auf dem Quell-Head vergleichen. Pro PR eine Zeile ausgeben, die seinen Head, seine Pfadanzahl, seine Blobanzahl und MATCH zeigt, plus eine Summe. Den Block wörtlich in die Beschreibung des Batch-PRs einfügen.

7. Den Batch-PR als Entwurf öffnen. Den Branch pushen, dann den Entwurf gegen main erstellen. Der Titel gibt die Anzahl der tatsächlich eingespielten PRs an, nicht die Anzahl der betrachteten:

   gh pr create --draft --base main --title "docs: land <k> reviewed docs PRs" --body-file <body-file>
   

8. Die Beschreibung schreiben. Einen Hinweis aufnehmen, dass der Build für einen reinen Dokumentations-Diff übersprungen wurde, die Liste der eingespielten PRs mit Dateizahlen und Heads, die übersprungenen PRs mit Gründen, alle Flags für den Reviewer und den Verifikationsblock. Den Zustand des neuen PRs erneut lesen und bestätigen, dass es ein Entwurf gegen main ist.

Fallstricke

• Die Draft-Regel ignorieren. Die Anweisungen eines Durchlaufs können einen fertig zur Überprüfung bereiten PR verlangen. Ihn als Entwurf öffnen, es sei denn, die Regeln des Durchlaufs sagen etwas anderes, und dies in der Beschreibung angeben.
• Ein Quell-PR, der auf einem anderen Branch basiert. Seine Dateien bestehen jede Pfadregel, aber ihr Einspielen auf main ändert die Bedeutung des PRs. Ihn nur einbeziehen, wenn die Regeln es erlauben, und mit dem genauen Commit kennzeichnen, der fallengelassen werden soll.
• Keine Merge-Basis. Eine Merge-Basis-Suche kann für einen solchen PR fehlschlagen, und ein Diff gegen die Basis führt dann zu einem Fehler. Die Live-Dateiliste als Quelle der Pfade verwenden. Querprüfung mit einem Diff gegen die Merge-Basis nur dort, wo eine existiert.
• Teilweises Einspielen. Ein PR, der Dateien ändert, die main bereits hat, kann übersprungen werden, selbst wenn seine anderen Dateien neu sind. Nicht nur einen Teil davon einspielen.
• Überflutung der Ausgabe mit Fehlern zu fehlenden Pfaden. Eine Prüfung, ob ein Pfad auf main existiert, gibt für jeden fehlenden Pfad einen Fehler aus. Standardfehler in diesen Prüfungen nach /dev/null umleiten.
• Den Abschlussbericht aufblähen. Die übersprungene Liste mit Gründen, die Flags und die Verifikationssummen melden. Nicht jeden Pfad einzeln auflisten.
• Fehlender Graph oder Index. Wenn ein Code-Intelligence-Index für das Repository nicht verfügbar ist, dies im Bericht angeben und die Pfadregeln nicht überspringen.

Verifikation

• Der Batch-PR ist ein Entwurf gegen main.
• Jeder eingespielte Datei-Blob stimmt mit seinem Quell-Head überein, wie im Verifikationsblock gezeigt.
• Keine geänderte Datei liegt außerhalb des Dokumentationsordners.
• Jeder übersprungene PR hat einen Grund in der Beschreibung.
• Die Quell-PRs sind unverändert. Diese Prozedur hat sie nicht zusammengeführt, genehmigt, geschlossen oder kommentiert.