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.
Alternativ kannst du die lokale Vorschau auch ohne make-Befehl erstellen. Auf der Konsole wechselst du
hierzu in das Unterverzeichnis page und erstellst die lokale Vorschau über den Befehl:
hugo server --cleanDestinationDir --environment manual --destination ../build/manual.
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
Der Remote-Name »upstream« kann frei gewählt werden bzw. auch nachträglich umbenannt werden.
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
Nach dem »push« eines eigenen neuen Branches wird dir auf der Konsole ein Link zum Erstellen des Pull-Request angezeigt.
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.