Arbeitsablauf

Diese Anleitung setzt voraus, dass du bereits über ein GitHub-Konto verfügst und Git installiert ist. Stelle sicher, dass Git in deinem PATH enthalten ist, indem du den Befehl git in einem beliebigen Terminal oder in der Eingabeaufforderung ausführst - es sollte keine Fehlermeldung angezeigt werden. Falls du Git noch nicht installiert hast, befolgen Sie diese Anleitung.

🔗Undokumentierte Features dokumentieren

Wir sind insbesondere daran interessiert, abgeschlossene Pull Requests, die Änderungen oder Erweiterungen der Dokumentation erforderlich machen, zu dokumentieren. PRs, die Dokumentation erfordern, sind mit dem GitHub Label documentation: pending versehen.

Übersicht über die nötigen Schritte:

  1. Siehe die Liste der PRs, die dokumentiert werden sollen an.

  2. Wähle ein Pull-Request aus, bei dem du verstehst, was in der Dokumentation getan werden muss.

  3. Führe die Änderungen entsprechend des unten erklären Workflows durch.

  4. Wenn du ein Pull Request erstellt, inkludiere einen Link zum in Schritt 1 ausgewählten PR.

🔗Arbeitsablauf zur Dokumentation

🔗Einmalige Einrichtung

Falls du git noch nicht lokal eingerichtet hast, benutze diese zwei Kommandos um deine Identität einzurichten.

  1. git config --global user.email "you@example.com"

  2. git config --global user.name "Your Name"

Falls du deine lokale git Instanz noch nicht mit GitHub authentifiziert hast, folge der Anleitung für **GitHub CLI ** hier. Die stellt sicher, dass die entsprechenden Schlüssel und Zugangsdaten eingerichtet werden.

Dann kannst du eine Kopie von dtdocs auf einen Computer klonen.

  1. Gehe zu https://github.com/darktable-org/dtdocs.

  2. Klicke Fork und dann Create fork.

  3. Du wirst nun auf die Seite deines eigenen dtdocs forks weitergeleitet. Klicke Code und dann kopiere den Link unter HTTPS.

  4. Öffne ein Terminal/Kommandozeile in dem Verzeichnis, in dem du das lokale Repository erstellen möchtest. Z.b. ‘C:\Users\YourUser\Documents' oder ‘home/youruser/Documents/’.

  5. Klone das dtdocs Repository mit: git clone https://github.com/<dein Benutzername>/dtdocs.git. Benutze die URL aus Schritt 3.

  6. Jetzt hast du eine Kopie des dtdocs repository auf deinem PC. Ein paar weitere Einrichtungsschritte folgen.

🔗Änderungen synchronisieren

  1. Gehe zu deinen repositories auf GitHub und wähle deinen dtdocs Fork.

  2. Klicke Sync Fork.

  3. Öffne das Terminal oder die Kommandozeile innerhalb deines lokalen dtdocs repository.

  4. Stelle sicher, dass du keine lokal ausstehenden Änderungen hast: git status; dann git checkout master (falls du dieser Anleitung folgst bist du bereits im Branch master).

  5. Führe git pull aus; dies stellt sicher, dass deine lokale Kopie mit deinem Fork auf GitHub aktuell ist.

Alternativ kannst du deinen Fork auch mittels der Kommandozeile synchronisieren:

  1. Stelle sicher, dass du keine lokalen ausstehenden Änderungen hast mittels git status und git checkout master.

  2. Überprüfe die eingerichteten Remote Repositories: git remote -v. Du solltest mindestens origin sehen deinen Fork). Wenn upstream noch fehlt, füge es im nächsten Schritt hinzu.

  3. Füge das dtdocs Repository als upstream hinzu (nur einmalig nötig): git remote add upstream https://github.com/darktable-org/dtdocs.git.

  4. Pulle den aktuellen Status des dtdocs Repository zu deiner lokalen Kopie: git pull upstream master.

  5. Pushe deine nun aktualisierte lokale Kopie zu deinem Fork auf GitHub: git push origin master.

🔗Einen Branch erzeugen, bearbeiten und ein Pull Request eröffnen

  1. Öffne ein Terminal oder die Kommandozeile im Verzeichnis deines lokalen dtdocs Repository.

  2. Führe git pull origin master aus, um die aktuelle Version von GitHub zu pullen.

  3. Führe git checkout -b branch-name aus und ersetze dabei branch-name durch einen selbstgewählten Namen, der zur geplanten Arbeit passt. Z.b. bei diesem PR https://github.com/darktable-org/darktable/pull/17589 könntest du den Branch dt-synch-edit-docs nennen.

  4. Erledige die geplante Arbeit.

  5. Verizifiere die veränderten Dateien mit git status. Falls du mehr Dateien verändert hast, als du absenden möchtest, kannst du mit git restore pfad/zur/datei die Datei zurücksetzen.

  6. Führe git add- A aus, dies “staged” deine Dateien, bereitet sie also zum Commit vor.

  7. Führe git commit -m "Dokumentation für dies und das". Gib innerhalb der Anführungszeichen eine kurze Beschreibung der erledigten Arbeit an.

  8. Führe git push --set-upstream origin branch-name aus. Ersetze branch-name mit dem vorher gewählten Namen.

  9. Erstelle dein Pull Request mit den unten folgenden Schritten.

  10. Falls du weitere Korrekturen (auch wenn das Pull Request bereits erstellt ist) durchführen möchtest, wiederhole einfach Schritte 3-8. Bei Schritt 3 kannst du -b weglassen und bei Schritt 8 nur git push ausführen.

  11. Wenn du mit der Arbeit fertig bist kannst du mit git checkout master zum Master Branch zurückkehren. Wir empfehlen, wenn du dich mit git noch nicht so gut auskennst, nur an einem PR auf einmal zu arbeiten.

🔗hugo lokal ausführen

hugo kann auch lokal ausgeführt werden, um eine lokale Live-Vorschau der Docs zu erstellen. Dies ist nützlich, um Formatierung, Links usw. zu überprüfen.

Führe hugo Server -D --disableFastRender aus dem Basisverzeichnis Ihres lokalen Repositories. Wenn keine Fehler aufgetreten sind, meldet das Terminal: Web Server is available at http://localhost:1313/usermanual/development/ (bind address 127.0.0.1) und die Website sollte auf der URL verfügbar sein. Hugo wird die Dateien auf Änderungen überwachen und bei Änderungen automatisch neu veröffentlichen. Wenn du eine bestimmte Seite geöffnet hast und Änderungen in der entsprechenden .md-Datei vornimmst, sollte der Browser auch die Seite neu laden, nachdem hugo automatisch neu veröffentlicht hat.

🔗Pull Request

  1. Rufe https://github.com/darktable-org/dtdocs/compare auf

  2. Klicke compare across forks. Wähle dein Repository, dann den Branch, an dem du gerade gearbeitet hast.

  3. Klicke Create Pull Request

translations