Anleitung für Pull Requests

Die Fedora-Dist-Git-Repositories ermöglichen Pull Requests, wodurch jeder ohne Maintainer-Status zu jedem Paket beitragen kann. Paketbetreuer können Pull Requests ebenfalls nutzen, um Mitbetreuern die Möglichkeit zu geben, die vorgeschlagenen Änderungen zu prüfen und sich in die Continuous integration von Dist-Git einzuklinken.

Für Pull-Request-Beiträge können dieselben Paketierungswerkzeuge und Arbeitsabläufe verwendet werden, die auch von Paketbetreuern genutzt werden. Ausgenommen hiervon sind bestimmte privilegierte Operationen, die nur von Paketbetreuern durchgeführt werden können, wie beispielsweise das Einreichen einer Bodhi-Aktualisierung.

Diese Anleitung beschreibt einen möglichen Arbeitsablauf zum Einreichen eines Pull Requests. Eine ausführlichere Anleitung zu den verwendeten Werkzeugen finden Sie in der Anleitung zur Wartung von Paketen. Diese Anleitung enthält zahlreiche Optionen, mit denen sich weitere Arbeitsabläufe erstellen lassen.

Diese Anleitung geht davon aus, dass Sie einen Pull Request für ein Paket namens some-package erstellen. Als Zielzweig für den Pull Request wird rawhide angenommen, da Rawhide ein deutlich häufigeres Änderungsziel als Release-Zweige ist. Jede andere Release-Version, wie z.B. f42, unterscheidet sich hauptsächlich im Namen des Zweiges.

Dieser Leitfaden geht außerdem davon aus, dass Sie kein Mitglied der Gruppe packager sind, und enthält separate Hinweise an Stellen, an denen diese Gruppenmitglieder etwas anders machen sollten.

Wann sollte man einen Pull Request erstellen?

Im Allgemeinen ähneln die Gründe für Pull-Requests bei Fedora-Paketen denen anderer Open-Source-Repositorys. Entweder nutzen Sie das Paket und möchten es für Ihre eigenen Zwecke verbessern, oder Sie tragen zu einem anderen Projekt oder Paket bei und müssen eine Änderung vornehmen, um Ihre eigene Arbeit zu ermöglichen. Oder Sie entdecken beim Durchsehen des Paket-Repositorys Verbesserungspotenzial und reichen einen Pull-Request ein, um die Betreuer zu unterstützen.

Ein Fedora-spezifischer Grund ist der Sponsoring-Prozess für Paketbetreuer, der von einem Paketierer-Kandidaten verlangt, seine Fähigkeiten im Bereich des Paketbaus unter Beweis zu stellen, was sehr bequem durch das Einreichen von Pull Requests erfolgen kann.

Ein sehr häufiger und oft einfacher Grund ist, dass die Fedora-Version eines Pakets nicht der neuesten Upstream-Version entspricht. Dem Paket können auch optionale Abhängigkeiten fehlen oder es verwendet suboptimale Bauoptionen, so dass nicht alle vom Upstream-Projekt bereitgestellten Funktionen unter Fedora vorhanden sind.

Voraussetzungen

Sie benötigen ein Fedora-Konto. In der Dokumentation Paketbauwerkzeuge installieren müssen Sie außerdem die Abschnitte Installieren und Konfiguration / Mock lesen und befolgen.

Klonen des Repositorys

Normalerweise arbeiten Paketbetreuer direkt im dist-git-Repository des Pakets, auf das nur sie Zugriff haben. Für Pull-Requests ist ein Fork erforderlich. Zwar lässt sich ein Fork über die Weboberfläche von src.fedoraproject.org erstellen und mit einfachen Git-Befehlen klonen, doch fedpkg fork bietet eine komfortable und einfache Methode über die Befehlszeile.

fedpkg clone --anonymous some-package
cd some-package
fedpkg fork

Falls fedpkg fork eine Fehlermeldung wegen eines fehlenden Page-Tokens ausgibt, befolgen Sie die in der Fehlermeldung angegebenen Anweisungen.

Diese Befehle erzeugen ein lokales Git-Repository mit den Remotes origin für das offizielle dist-git-Repository des Pakets im Fetch-Only-Modus und einem weiteren mit Ihrem Fedora-Benutzernamen, das auf Ihren Fork verweist, in den ebenfalls gepusht werden kann:

$ git remote --verbose
origin	https://src.fedoraproject.org/rpms/some-package.git (fetch)
origin	https://src.fedoraproject.org/rpms/some-package.git (push)
username	https://src.fedoraproject.org/forks/username/rpms/some-package.git (fetch)
username	https://src.fedoraproject.org/forks/username/rpms/some-package.git (push)

Verzweigung (Branching)

Genau wie bei jedem anderen Pull Request für jedes andere Projekt, erstellen Sie einen Git-Zweig für Ihre Änderungen:

git switch -c my-changes

Änderungen anwenden

Bei Pull Requests sind die lokalen Änderungen und deren lokale Tests für die Betreuer genau dasselbe. Zum Beispiel:

# die gwünschten Änderungen in der spec-Datei vornehmen
gedit some-package.spec
# die referenzierten Quellen auf den lokalen Rechner herunterlasen
spectool -g some-package.spec
# prüfen, ob sich das geänderte Paket noch bauen lässt
fedpkg --release rawhide mockbuild
# das Paket installieren und testen

Quellen aktualisieren

Nur Mitglieder der Gruppe packager können Quellen im Lookaside-Cache aktualisieren. Wenn heruntergeladene Quellen geändert werden müssen, kann ein Nicht-Paketierer bestenfalls die Datei sources mit der korrekten Prüfsumme aktualisieren:

fedpkg new-sources --offline some-package-1.2.3.tar.gz

Wenn Sie der Gruppe packager angehören, können Sie --offline aus dem Befehl entfernen, sodass das Quellarchiv hochgeladen wird. Andernfalls muss dies der Betreuer tun, der den Pull Request schließlich zusammenführt. Stellen Sie in diesem Fall sicher, dass der Merge Request eindeutig auf das Quellarchiv verweist. Normalerweise geschieht dies durch die Verwendung einer URL im Source-Tag der .spec-Datei. Alternativ kann ein Kommentar in der .spec-Datei verwendet werden.

Committen und Pushen

Erstellen Sie einen Commit Ihrer Änderungen, schreiben Sie eine aussagekräftige Commit-Meldung und pushen Sie Ihren Zweig in Ihren Fork:

git add <geänderte Dateien>
git commit
git push username HEAD

Beachten Sie, dass, wenn das Paket rpmautospec verwendet, die Commit-Nachricht ausgewertet wird, um den Eintrag im Paket-Changelog zu erstellen.

Den Pull Request erstellen

Wenn Sie Ihre Änderungen in Ihren Fork übertragen, erhalten Sie als Ausgabe einen Link zum Erstellen eines Pull Requests:

remote: Create a pull-request for my-changes
remote:    https://src.fedoraproject.org/fork/username/rpms/some-package/diff/rawhide..my-changes

Sie können auch in der Pagure-Weboberfläche einen Pull Request für jeden Zweig Ihres Forks erstellen.

Das Pull-Request-Formular fordert Sie auf, eine Beschreibung anzugeben, die automatisch mit dem Commit-Changelog ausgefüllt wird. Tragen Sie dort alle relevanten Informationen ein und senden Sie das Formular ab.

Falls Sie den Lookaside-Cache im Schritt Quellen aktualisieren nicht füllen konnten, geben Sie diese Information bitte an und bitten Sie einen Betreuer, dies zu erledigen.

Continuous integration

Dist-Git-Repositories sind standardmäßig mit CI verbunden. Für jeden Pull Request wird ein Koji-Scratch-Build und ein Test auf Installierbarkeit durchgeführt. Die Ergebnisse werden auf der Webseite des Pull Requests angezeigt, sobald sie verfügbar sind. Auch wenn ein CI-Fehler das Mergen nicht verhindert, sollte das Ergebnis im Idealfall positiv sein. Falls der CI-Test fehlschlägt, empfiehlt es sich, das Problem zu beheben.

Falls Sie den Test-Build in Pull Requests erneut ausführen müssen, genügt ein Kommentar mit [citest].

Paketbetreuer können auch die erweiterte CI-Lösung Zuul aktivieren.

Review

Die Überprüfung von Pull-Requests erfolgt wie bei jedem anderen Open-Source-Projekt. Im Idealfall reagiert ein Betreuer schnell auf Ihren Pull-Request und führt ihn entweder direkt zusammen, stellt Fragen oder fordert Änderungen an. Beantworten Sie die Fragen, führen Sie die gewünschten Änderungen durch und übertragen Sie diese in denselben Zweig.

Beachten Sie, dass viele Fedora-Pakete von Freiwilligen gepflegt werden und es keine festen Fristen für die erwartete Reaktionszeit auf Pull-Anfragen gibt. Daher kann die Überprüfung erst nach Tagen oder Wochen erfolgen. Sollten Sie die Reaktionszeit als zu lang empfinden, können (und sollten) Sie die Schritte in den Richtlinien für nicht reagierende Paketbetreuer befolgen.

Nach dem Merge

Der Pull Request ist abgeschlossen, sobald ein Betreuer ihn zusammengeführt („merged“) hat. Anschließend muss der Betreuer noch Folgendes tun:

Den Lookaside-Cache aktualisieren, falls Sie es nicht tun können.
Einen Build mit fedpkg build anstoßen (da dies jeder Paketierer für jeden Commit in einem Release-Zweig für jedes Paket tun kann, können Sie dies theoretisch auch tun, wenn Sie Paketierer sind. In der Praxis wird es jedoch der Betreuer sein, der Ihren Pull Request zusammenführt, da er den Build unmittelbar nach dem Zusammenführen starten kann.)
Falls Änderungen an einem anderen Zweig als rawhide vorgenommen wurden, eine Bodhi-Aktualisierung einreichen.

Want to help? Learn how to contribute to Fedora Docs ›