Einen lokalen Arbeitsablauf für Fedora-Dokumentation anlegen und verwenden
In einer lokalen Umgebung können Sie Ihre Dokumente offline erstellen oder bearbeiten. Sie verwenden dazu ein lokales Git-Repository, das alle Dokumente und Bearbeitungswerkzeuge enthält. Nach Abschluss der Bearbeitung können Sie die Dokumente in einer lokalen Version der Dokumentationsseiten in der Vorschau anzeigen. Dies ist mit Abstand die flexibelste Art, mit Dokumentations-Repositories zu arbeiten, da sie sich optimal an individuelle Arbeitsabläufe und Arbeitsgeräte anpassen lässt. Eine lokale Schreibumgebung ermöglicht Ihnen den vollen Zugriff auf alle Ressourcen, die Sie regelmäßig an Ihrem Arbeitsplatzrechner verwenden, und ist daher perfekt auf Ihren Arbeitsstil abgestimmt. Sie eignet sich besonders für die Erstellung einer komplett neuen Dokumentation zu einem Thema oder für die Überarbeitung einer bestehenden Dokumentation. Dieser Artikel verwendet die Fedora-Projekt-Repositories in GitLab als Beispiel, der gesamte Prozess lässt sich jedoch auf Pagure- und GitHub-Projekte übertragen.
Voraussetzungen
-
Sie müssen die Grundvoraussetzungen für das Schreiben von Beiträgen zur Dokumentation erfüllen.
-
Der Arbeitsablauf nutzt in den meisten Schritten Befehlszeilenwerkzeuge. Daher sind Vorkenntnisse im Umgang mit dem Linux-Terminal erforderlich oder müssen parallel erlernt werden.
Einrichten einer Autorenumgebung
Vorbereitungen
-
Verwenden Sie SSH-Schlüssel zur Authentifizierung am GitLab-Remote-Server.
-
Ein GPG-Schlüssel (GNU Privacy Guard) dient zum Signieren der verifizierten Commits.
In GitLab wählen Sie Preferences - User Settings - Add an SSH Key / a GPG Key
Git und Podman sind standardmäßig in Fedora Workstation enthalten. Der Podman-Container wird automatisch eingerichtet.
Erstellen Sie ein lokales Unterverzeichnis, in dem die Kopie des Dokumentations-Repositorys gespeichert wird
Erstellen Sie das Hautpverzeichnis mit mkdir Verzeichnisname
$ mkdir ~/FedoraDocs
Richten Sie das Repository ein
Ein Projekt forken
Gehen Sie in GitLab zum Upstream-Repository und klicken Sie auf den Fork-Knopf. Wählen Sie einen Namensraum (Ihre GitLab-ID) und eine Sichtbarkeitsstufe für das geforkte Projekt. Dadurch wird ein Fork in Ihrem GitLab-Konto erstellt.
Falls Sie keine Berechtigung zum Erstellen eines Projekts haben, öffnen Sie ein Ticket in GitLab, damit eines für Sie erstellt wird.
Klonen Sie das Repository
Klicken Sie in Ihrem geforkten Repository auf den blauen Knopf Clone und wählen Sie im Ausklappmenü Clone with SSH aus. Kopieren Sie den Link in Ihre Zwischenablage.
Wechseln Sie in Ihr Hauptdokumentationsverzeichnis und klonen Sie das Repository.
$ cd FedoraDocs
Beim Klonen eines Repositorys kann der Name des neuen Verzeichnisses als zusätzliches Argument angegeben werden. Dadurch wird ein Unterverzeichnis namens „ContributorsGuide“ erstellt und das Repository in dieses Verzeichnis geklont.
$ git clone <GIT URL> ContributorsGuide
$ cd ContributorsGuide
Überprüfen Sie den aktuellen Zweig, der „main“ oder „master“ heißt.
$ git status
Zeigen Sie alle Zweige auf der Gegenseite an.
$ git branch -v -a
Erstellen Sie einen Zweig und wechseln Sie in ihn:
$ git checkout -b <neuer-Zweig>
Arbeiten am Inhalt
Öffnen Sie die Datei(en) mit einem Texteditor Ihrer Wahl, bearbeiten Sie sie und speichern Sie sie.
Ihren Fork mit dem Upstream-Repository synchronisieren
$ git remote -v
Dadurch wird der Fork in Ihrem Konto als Ursprung angezeigt.
Gehen Sie zum Upstream-Repository, wählen Sie im Aufklappmenü den Knopf „Clone“ aus und kopieren Sie „Clone with SSH“.
$ git remote add upstream <SSH-URL>
Führen Sie den folgenden Befehl aus, um sowohl den Ursprung als auch den Upstream anzuzeigen.
$ git remote -v
Um Ihren Fork mit dem Upstream synchron zu halten:
$ git checkout main $ git fetch upstream
$ git pull upstream main
Dieser Befehl lädt die aktuellsten Commits vom Upstream-Repository in Ihren lokalen Zweig.
$ git push origin main
Dieser Befehl überträgt Ihre lokalen Commits an den „main“- (Haupt-)Zweig des Ursprungs-Remotes.
Skripte für die lokale Vorschau ausführen
Wechseln Sie in das Verzeichnis, in dem sich das geklonte Repository befindet, und führen Sie die Bauskripte im Terminal aus.
$ ./docsbuilder.sh
Vorschau in Ihrem Browser unter der Adresse localhost:8080
Speichern Sie Ihre Arbeit
Um zu sehen, was die Befehle git add und git commit bewirkt haben.
$ git status
Änderungen hinzufügen, die committed werden sollen:
$ git add -A
Alternativ können Sie alle Dateien im aktuellen Arbeitsverzeichnis mit folgendem Befehl hinzufügen:
$ git add .
Bereiten Sie die Änderungen zum Hochladen vor. Dadurch wird ein Texteditor geöffnet, in dem Sie eine Commit-Nachricht hinzufügen können.
$ git commit -s
Der Befehl git log zeigt den Projektverlauf und spezifische Änderungen an.
$ git log
Laden Sie die Änderungen in den Zweig in Ihrem Fork hoch.
$ git push origin <Zweigname>
Merge Requests erstellen
Wechseln Sie in GitLab zu Ihrem Fork des Repositorys.
Klicken Sie im linken Menü auf „Merge Requests“ und wählen Sie dann in der Mitte die blaue Option „New Merge Request“ aus.
Wenn Sie in einem Fork arbeiten, wählen Sie Ihren Fork des Repositorys als Quellzweig aus.
Wählen Sie in der Auswahlliste „Target branch“ den Zweig aus dem Upstream-Repository als Ziel-Zweig aus.
Klicken Sie auf „Compare branches and continue“.
Wählen Sie „Create merge request“.
Want to help? Learn how to contribute to Fedora Docs ›