Zur Dokumentation beitragen

Vor deinem ersten Beitrag

Bevor du an der Dokumentation mit schreiben kannst, musst du noch folgendes tun:

• Erstelle ein kostenloses Konto bei GitHub. GitHub ist ein Dienst für die Versionsverwaltung mit Git für Software-Projekte und beheimatet unter anderem die Contao-Dokumentation.
• Die Dokumentation wird in Markdown geschrieben, mache dich mit der Syntax und den Formatierungsmöglichkeiten dieser Auszeichnungssprache vertraut. Zudem hast du zu Beginn des Dokuments die Möglichkeit, entsprechende Variablen und Metadaten zu pflegen.

Kleine Fehler korrigieren

Wenn du während des Lesens der Dokumentation einen Tippfehler entdeckst oder etwas umformulieren möchtest, ist es am einfachsten, dies direkt über GitHub zu tun.

Seite bearbeiten und Fork des Repositories erstellen

Klicke auf den Link »Diese Seite bearbeiten« in der oberen rechten Ecke und du wirst zu GitHub weitergeleitet:

Bei deinem ersten Beitrag wirst du gebeten, einen Fork vom Repository »contao/docs« zu erstellen. Klicke auf »Fork this repository«.

Inhalt bearbeiten

Bearbeite den Inhalt, beschreibe deine Änderungen und klicke auf die Schaltfläche »Propose file change«.

Branch und Commit erzeugen

GitHub wird nun einen neuen Branch in deinem Fork und einen Commit für deine Änderungen erzeugen. Ausserdem wird eine Vorschau deiner Änderungen angezeigt:

Wenn alles korrekt ist, klicke auf die Schaltfläche »Create pull request«.

Weitere Änderungen vor dem Pull-Request hinzufügen

Möchtest du vor dem Pull-Request noch weitere Inhalte bearbeiten, beispielsweise Anpassungen entsprechender Übersetzungen, wechselst du stattdessen zunächst zu deinem Fork und wählst den neu erstellten Branch aus. Hier kannst du deine zusätzlichen Änderungen vornehmen und kommentieren.

Im Anschluss kannst du dann abschließend den Pull-Request über »Contribute/Open pull request« starten.

Pull-Request erzeugen

Da du keine Berechtigungen hast, direkt Änderungen im offiziellen Repository zu vollziehen, stellst du eine Anfrage an die Berechtigten des Repositories deine Änderungen in das offizielle Repository zu übernehmen.

Falls nötig, kannst du noch letzte Anpassungen an deinen Pull-Request vornehmen. Klicke erneut auf die Schaltfläche »Create pull request«.

Herzlichen Glückwunsch! Du hast soeben einen Pull-Request für die offizielle Contao-Dokumentation erstellt! Die Community wird nun deinen Pull-Request überprüfen und (möglicherweise) Änderungen vorschlagen.

Fork aktualisieren

Falls du weitere Änderungen vorschlagen möchtest, überprüfe zuvor, ob dein Fork auf dem aktuellen Stand ist. Über GitHub kannst du dann deinen Fork über »Fetch upstream« synchronisieren.

Einen Beitrag für die Dokumentation schreiben

Wenn du einen umfangreichen Beitrag planst oder du es vorziehst, an deinem eigenen Computer zu arbeiten, lese hier weiter und wir zeigen dir eine alternative Möglichkeit auf, wie du Pull-Requests an die Contao-Dokumentation senden kannst.

Git installieren

Dazu musst du Git auf deinem Betriebsystem installieren.

Fork des Repositories erstellen

Wenn du noch kein Konto bei GitHub hast, erstelle eines und wechsle zum offiziellen Contao-Dokumentations-Repository unter github.com/contao/docs. Klicke auf die Schaltfläche »Fork«, um das Repository auf dein persönliches Konto zu übertragen. Dies ist nur erforderlich, wenn du zum ersten Mal etwas zur Dokumentation beiträgst.

Klone das geforkte Repository

Klone das geforkte Repository auf deinem lokalen Rechner:

Erstelle ein Verzeichnis mit dem Namen contao und wechsle mit change directory in dieses.

cd contao

Beim Klonen installierst du das Hugo Learn Theme als Submodul von git.

git clone --recurse-submodules git@github.com:DEIN-GITHUB-BENUTZERNAME/docs.git ./

oder

git clone --recurse-submodules https://github.com/DEIN-GITHUB-BENUTZERNAME/docs.git ./

Hugo-Site-Generator installieren

Die Dokumentation wird mit dem Hugo-Site-Generator erstellt, daher musst du Hugo zuerst auf deinem System installieren. Falls du Hugo bereits zu einem früheren Zeitpunkt installiert hast, empfiehlt sich eine Aktualisierung der Software.

Vorschau der Dokumentation erstellen

Das Erstellen einer Vorschau der Dokumentation erfolgt mit dem make-Befehl. Es stehen verschiedene Befehle zur Verfügung, je nachdem, welchen Teil der Dokumentation du bauen möchtest.

make build-dev
make build-manual

Erstellt die gesamte Dokumentation im Build-Verzeichnis.

make live-dev
make live-manual

Erstellt eine Live-Vorschau, welche automatisch Änderungen im Verzeichnis docs verfolgt und das Frontend neu lädt. Das Frontend ist über localhost:1313 erreichbar.

make clean

Bereinigt das Build-Verzeichnis.

Fork mit dem Original-Repository synchronisieren

Wenn du schon länger nicht mehr mit deinem Fork gearbeitet hast, kann es sein, dass bei deinem Fork auf GitHub folgende Meldung This branch is 7 commits behind contao:main. ausgegeben wird.

Bevor du also Anpassungen an der Doku vernimmst, kannst du dafür sorgen, dass dein Fork mit dem Original-Repository synchronisiert wird.

Füge das Original-Repository einmalig als neues Remote-Repository hinzu und gebe es als Upstream-Repository an.

git remote add upstream https://github.com/contao/docs.git

Hole die Daten des Upstream-Repositories mit fetch.

git fetch upstream

Die Commits, die sich von deinem Fork unterscheiden, sind jetzt in deiner lokalen Umgebung in getrennten Branches untergebracht. Mit dem nächsten Befehl führst du diese zusammen.

git merge upstream/main

Jetzt führst du noch folgendes Kommando aus, um deinen Fork zu aktualisieren.

git push

Auf GitHub wird bei deinem Fork jetzt die Meldung This branch is even with contao:main. ausgegeben.

Branch erstellen

Bevor du den Inhalt bearbeitest, sorgen wir mit dem Erstellen eines eigenen Branches (Verweis auf einen Snapshot) dafür, dass du mit anderen parallel an der Dokumentation arbeiten kannst. Branches sind also unabhängige Entwicklungszweige.

Erstelle einen neuen Branch aus dem aktuellen.

git checkout -b DEIN-BRANCHNAME

Inhalt bearbeiten

Nachdem die Grundvoraussetzung zum Dokumentieren erfüllt sind, kannst du die Doku jetzt mit deinem Beitrag erweitern.

Die Dateien der Dokumentation findest du im Verzeichnis docs deiner lokalen Hugo-Installation.

• Die Contao Entwicklerdokumentation befindet sich im Verzeichnis dev.
• Das Contao Handbuch für Anwender*innen befindet sich im Verzeichnis manual.

Wenn alle Anpassungen bzw. Ergänzungen vorgenommen wurden, spielen wir diese auf unseren Fork zurück.

Änderungen in dein Repository übertragen

Jetzt liegen die Daten auf deinem lokalen Rechner und müssen im nächsten Schritt an dein Repository auf GitHub übertragen werden.

Mit folgendem Befehl kannst du alle Änderungen für den nächsten Commit stagen.

git add .

Danach fügst du die Änderungen dem Lokalen-Repository hinzu.

git commit -m "Eine aussagekräftige Commit-Nachricht eingeben"

Um die Änderungen an dein entferntes Repository zu senden, führe folgenden Befehl aus.

git push origin DEIN-BRANCHNAME

Pull-Request erzeugen

Rufe deinen Fork auf GitHub (https://github.com/DEIN-GITHUB-BENUTZERNAME/docs) auf.

Klicke in der Mitteilung auf »Pull request.

Vergleiche die Änderungen und schliesse diesen Schritt mit dem Klick auf »Create pull request« ab.

Bestätige das Erstellen eines Pull requests mit »Create pull request«.

Herzlichen Glückwunsch! Du hast soeben einen Pull-Request für die offizielle Contao-Dokumentation erstellt! Die Community wird nun deinen Pull-Request überprüfen und (möglicherweise) Änderungen vorschlagen.

Einen Pull-Request ändern

Finde den Branch, in welchem dein Pull-Request ist und checke ihn aus. Sagen wir, es sei der Branch patch-4:

git checkout patch-4

Bearbeite die Dateien, die geändert werden sollen.

Mit folgendem Befehl kannst du alle Änderungen für den nächsten Commit stagen.

git add .

Danach fügst du die Änderungen dem Lokalen-Repository hinzu.

git commit -m "Eine aussagekräftige Commit-Nachricht eingeben"

Um die Änderungen an dein entferntes Repository zu senden, führe folgenden Befehl aus.

git push origin patch-4

Damit ist dein Pull-Request angepasst.