Arbeitsablauf

These instructions assume that you already have a github account and have installed Git as well. Make sure that git is in your PATH by executing the command git in any terminal or cmd and checking that it doesn’t output an error such as “command not found”. If you don’t have git installed, follow these instructions.

🔗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.

🔗Running hugo locally to see changes

hugo can also be executed locally to create a local live preview of the docs. This is useful to check for formatting, links etc.

Execute hugo server -D --disableFastRender from the base directory of your local repository. When no errors are encountered, the terminal will report: Web Server is available at http://localhost:1313/usermanual/development/ (bind address 127.0.0.1) and the site should be available at the URL. Hugo will monitor the directory for changes and redeploy upon changing files automatically. When you have a specific page open and make changes to the corresponding .md file the browser should also reload the page after hugo has automatically redeployed.

🔗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