Hotfix-Herkunft

Ein Hotfix-Branch wird vom Release abgezweigt, das in Produktion läuft, und die Korrektur wird vom Standard-Branch übernommen. Hotfix-Herkunft stellt sicher, dass auf ihm nichts anderes passiert. Auf einem Branch, der zu deinem Hotfix-Muster passt (standardmäßig hotfix/*), muss jeder Commit:

1. ein git cherry-pick -x eines Commits auf dem Standard-Branch des Repositorys sein;
2. dessen gemergter Pull Request dein Fast-Track-Label trägt (standardmäßig fast-track);
3. und dessen Änderung dieselbe ist wie die des Quell-Commits.

fremforge prüft jeden Commit eines Pull Requests in einen Hotfix-Branch und jeden Commit, der in einen gepusht wird, und meldet das Ergebnis als Commit-Status fremforge/hotfix-provenance: success oder failure mit dem ersten Commit, der nicht besteht, und dem Grund. Du kannst ihn zu einem erforderlichen Check machen.

Hotfix-Herkunft ist standardmäßig ausgeschaltet. Ein Owner der Organisation schaltet sie über die API ein.

Einen Hotfix erstellen

# 1. Fix it on the default branch first, through a pull request with the label `fast-track`.
# 2. Cut the hotfix branch from the production tag and push it:
git switch -c hotfix/1.4.2 v1.4.1
git push -u origin hotfix/1.4.2
# 3. Carry the fix over on a branch of its own. -x writes the "(cherry picked from commit ...)" line:
git switch -c backport/login-fix
git cherry-pick -x <the commit the merge put on main>
git push -u origin backport/login-fix
# 4. Open a pull request from backport/login-fix into hotfix/1.4.2.

Cherry-picke den Commit, den der Merge auf den Standard-Branch gelegt hat: den Squash-Commit oder den Merge-Commit (git cherry-pick -x -m 1 <merge>). fremforge findet den Pull Request der Quelle über diesen Commit. Bei Rebase-Merges lässt sich so nur der letzte Commit eines rebasten Pull Requests finden.

Was fehlschlägt, und warum

Der Status nennt den ersten fehlgeschlagenen Commit und die Anzahl der weiteren. Jeder Commit ist in der Erklärung aufgeführt.

So entscheidet fremforge:

• Welche Commits zählen. Bei einem Pull Request in einen Hotfix-Branch seine eigenen Commits. Bei einem Push in einen Hotfix-Branch jeder Commit auf dem Branch, der nicht auf dem Standard-Branch ist. Das Produktions-Tag, von dem der Branch abgezweigt wurde, ist auf dem Standard-Branch und zählt daher nie. Zweige Hotfix-Branches von einem Commit des Standard-Branches ab.
• Force-Pushes werden von Grund auf geprüft: fremforge betrachtet den ganzen Branch, nie nur die Commits des letzten Pushs.
• Der Änderungsvergleich funktioniert wie git patch-id: Er vergleicht die Zeilen, die jeder Commit hinzufügt und entfernt, Datei für Datei, und ignoriert dabei Leerzeichen, Zeilennummern und die umgebenden Zeilen. Ein Cherry-Pick auf ein älteres Release passt daher zu seiner Quelle. Du kannst ihn ausschalten (diff_check: false).
• Ein nach dem Merge hinzugefügtes Label zählt. fremforge liest die Labels des Quell-Pull-Requests, wenn es prüft. Wird das Label zu einem gemergten Pull Request hinzugefügt, werden die offenen Hotfix-Pull-Requests dieses Repositorys innerhalb von Sekunden erneut geprüft.
• Commits von Bots bekommen keine Ausnahme. Der Backport eines Bots ist ein Cherry-Pick wie jeder andere.
• Nachdem ein Pull Request gemergt wurde. Bei einem Push gilt der Squash- oder Merge-Commit, den ein gemergter Pull Request in denselben Hotfix-Branch erzeugt hat, als geprüft, sofern fremforge/hotfix-provenance auf diesem Pull Request bestanden hat.

Der Status besteht nie aus Versehen

Kann fremforge die Prüfung nicht abschließen, zum Beispiel weil das Repository nicht rechtzeitig gelesen werden konnte (30 Sekunden), ist der Status pending mit einem entsprechenden Hinweis, und er wird innerhalb von 5 Minuten erneut geprüft. Er ist nie success für einen Commit, den fremforge nicht prüfen konnte.

Auf einem Branch, der kein Hotfix-Branch ist, meldet fremforge nichts, es sei denn, die Regel dieses Branches verlangt fremforge/hotfix-provenance. Dann meldet es success, „Not a hotfix branch“, damit kein Pull Request darauf wartet. Dasselbe gilt für ein Repository, in dem Hotfix-Herkunft ausgeschaltet ist: „not evaluated“.

fremforge meldet den Status binnen Sekunden, nachdem ein Pull Request geöffnet, gepusht, bearbeitet oder auf einen anderen Ziel-Branch umgestellt wurde, und nach einem Push in einen Hotfix-Branch. Ein Job alle 5 Minuten prüft jeden offenen Hotfix-Pull-Request erneut, dessen Status fehlt, pending oder failure ist.

Einschalten

curl -X PUT https://frem.sh/_app/api/v1/orgs/<org>/hotfix-provenance/settings \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "on", "branch_pattern": "hotfix/*", "required_label": "fast-track"}'

Das Token braucht policy:write; GET auf denselben Pfad braucht policy:read. Jede Änderung wird als hotfix_provenance.settings_updated im Audit-Log erfasst.

Als erforderlichen Check festlegen

curl -X PUT https://frem.sh/_app/api/v1/orgs/<org>/hotfix-provenance/enforcement \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo": "*"}'

repo ist ein Repository-Name oder * für jedes Repository, auch später angelegte. fremforge meldet den Status zuerst auf jedem offenen Pull Request in einen Hotfix-Branch und fügt erst dann fremforge/hotfix-provenance zu der Branch-Regel hinzu, die wie das Muster heißt (zum Beispiel eine Regel namens hotfix/*), wobei die übrigen Checks der Regel erhalten bleiben. Ein Merge über die Webseite, die API oder die Merge-Warteschlange wartet dann darauf.

fremforge legt nie eine Branch-Regel an. Ein Repository ohne Regel für das Muster wird unter unprotected aufgeführt; lege die Regel an (Einstellungen → Branches), und der Job fügt den Check innerhalb von 5 Minuten hinzu. DELETE auf denselben Pfad mit demselben Body entfernt ihn wieder. Das Token braucht policy:write. Beides wird im Audit-Log erfasst, als hotfix_provenance.enforcement_enabled und hotfix_provenance.enforcement_disabled.

Warum ein Pull Request besteht oder fehlschlägt

curl https://frem.sh/_app/api/v1/orgs/<org>/repos/<repo>/pulls/<number>/hotfix-provenance \
  -H "Authorization: Bearer $FREMFORGE_TOKEN"

Die Antwort listet jeden Commit auf: ob er bestanden hat, den Quell-Commit, den seine Zeile nennt, den Pull Request der Quelle und, bei einem fehlgeschlagenen Commit, das problem und den Grund in Worten. Das funktioniert auch, solange Hotfix-Herkunft ausgeschaltet ist, sodass du es zuerst an einem echten Pull Request ausprobieren kannst. Das Token braucht findings:read oder Lesezugriff auf das Repository.