Hinweis: Ich erstelle diesen Post als einen Wiki-Artikel, um eine Anleitung zu schaffen, die Neulingen hilft zur OpenBikeSensor-Website, speziell der Dokumentation, beizutragen. Editier diesen Post gern, wenn du eine Idee hast, ihn zu verbessern!
Pull Requests und Forks
Unsere Website und die Dokumentation des OpenBikeSensor gehören fest zusammen und werden im Github-Repository openbikesensor/openbikesensor.github.io gepflegt. Dort verwenden wir einen Workflow basierend auf Pull-Requests, um Änderungen vorzuschlagen und in die Website einfließen zu lassen.
Um etwas beizutragen, benötigst du einen Account auf github.com. GitHub ist eine Seite zum Verwalten und Veröffentlichen von OpenSource-Projekten, und keine unübliche Wahl. Du findest dort auch viele andere Projekte und kannst selbst deine Werke veröffentlichen.
Eine gute Grundlage für die Arbeit mit Pull-Requests und Forks ist das deutschsprachige Git Book, speziell dieses Kapitel:
https://git-scm.com/book/de/v2/GitHub-Mitwirken-an-einem-Projekt
Nicht alles davon ist nötig, aber ein gutes Grundwissen zum Vorgehen wird vermittelt. Viel einfacher ist der Einstieg, wenn du den Web-Editor von Github verwendest. In deinem eigenen Fork kannst du dann direkt im Browser Dateien editieren und Commits erstellen. Bitte denke dabei an eine aussagekräftige Beschreibung des Commits (commit message).
Reviews
Wenn du einen Pull Request (PR) gestellt hast, wird sich jemensch diese Änderungen anschauen und dir unter Umständen Feedback geben, das du noch einarbeiten solltest. Erst dann werden die Änderungen akzeptiert und in den Branch main einfließen gelassen (merged).
Alle, die bereits einmal erfolgreich an der Berarbeitung der Website teilgenommen haben, werden in das „website-team“ der Github-Organisation OpenBikeSensor eingeladen – auch du! Ab dann ist es deine Aufgabe, die Änderungen Anderer auf Plausibilität, Korrektheit, Rechtschreibung und Form zu prüfen, gegebenenfalls Nacharbeiten anzufordern (request changes), und mit dem:der Autor:in des PRs Austausch zu stehen, bis diese ebenfalls gemerged werden. Dieses Vier-Augen-Prinzip sorgt für eine hohe Qualität und verteilt die Verantwortung für den Inhalt auf mehrere Schultern 
Hugo und Markdown
Die Website wird automatisch aus den Quelldateien zusammengestellt und veröffentlicht. Dafür verwenden wir den „static website builder“ hugo mit dem Theme docsy. Die meisten Seiten schreiben wir dabei im Format Markdown. Die Dokumentation von hugo ist sehr umfangreich und erklärt alle weiteren Features.
Du solltest, wenn du leicht komplexere Änderungen (also mehr als nur einen Stichpunkt, einen Satz oder einen Tippfehler) vorschlagen möchtest, auf den Web-Editor von Github verzichten, und stattdessen auf deinem PC sowohl git als auch hugo (extended version!) installieren. Im Repository selbst gibt es eine Anleitung (README.md), die erklärt wie du hugo dann ausführst.
Dies erlaubt dir eine lokale Vorschau der erstellten Website, bevor du überhaupt einen Commit machst oder einen Pull Request erstellst. Das ist besonders hilfreich, um zu sehen, ob dein Quelltext fehlerhaft ist, wie dein Markdown am Ende aussieht, und ob deine neu erstellte Seite auch im Menü angezeigt wird.
Test-Seite / Branches
Wir verwenden zwei Branches auf Github:
-
mainist der aktuelle Stand des Quelltexts, der zum Weiterarbeiten verwendet wird. Der letzte Stand vonmainist immer auf der Testseite https://test.openbikesensor.org zu sehen. -
productionist der aktuelle Stand der Website, und wird automatisch auf https://openbikesensor.org veröffentlicht
Bitte stelle Pull-Requests immer gegen main, sodass das Website-Team die Gelegenheit hat, nach dem Akzeptieren der Änderung die neue Website auf der Testseite anzusehen, bevor sie im Internet für alle sichtbar wird.
Mitglieder der Gruppe website-team können den aktuellen Stand von main auf production übertragen, wenn sie es für sinnvoll halten – zum Beispiel, nachdem ein Pull Request gemerged wurde und die Änderung auf der Testseite gut aussieht. Dafür verwenden wir folgendes Kommando:
git fetch origin && git push origin/main:origin/production
Issues in Github
Issues sind Arbeitsaufträge, die es zu erledigen gilt. Das können Vorschläge zu neuen Inhalten, zum Design oder sonstige TODOs sein. Wir pflegen diese auf Github, besprechen dort auch Ideen, und koordinieren uns, wer was beiträgt:
Bitte nutze Github Issues für alle inhaltlichen Themen zur Website, also Vorschläge oder Inhaltsfehler.
Noch Fragen?
Bitte antworte nicht auf diesen Post, sondern erstelle ein neues Thema in der Kategorie #design-entwicklung:docs für Hilfestellung zum Prozess. Inhaltliche Arbeit, also Ideen zur Website, oder Fehler die du findest, formulierst du lieber als ein Issue auf Github (s.o.).