layout	permalink
page	/contribute/

Webseite www.openost.ch

Wie kann ich mithelfen?

Erst einmal: Wir freuen uns über DEINE Mithilfe 👍🎉

Wenn du Ideen oder Fragen hast, über einen Schreibfehler gestolpert bist, etwas nicht verständlich findest oder uns loben / kritisieren möchstest, dann freuen wir uns riesig von dir zu hören!

Wir verwalten und diskutieren unsere Aufgaben mittels Github Issues. Wenn du mit Github nicht vertraut bist, dann schreib uns einfach eine E-Mail!

Am wichtigsten ist, dass du dich meldest - wir helfen dir geren weiter!

Bevor du loslegst....

Um mitarbeiten zu können, solltest du ein Grundwissen über Git haben. Ein guter Einstieg ist das Interaktive Git Tutorial von Github.

Grob können wir die folgenden Arten von Beiträgen unterscheiden:

1. Erweitern und Korrigieren von Dokumentationen und Artikeln zu Programmen
2. Eigene Tipps & Tricks
3. Änderungen am Layout und der Struktur der Webseite

Für reine Textbeiträge (1 und 2) musst du nicht wirklich verstehen, wie die Webseite zusammengebaut wird. Alle Inhalte werden in Textdateien in den Verzeichnissen _hsr, _app, tipps und pages verwaltet (siehe Seitenhierarchie). Diese Textdateien sind in Markdown geschrieben. Die einfache Einführung in Markdown von Designbits ist ein guter Einstiegspunkt - eine etwas ausführlichere Syntaxbeschreibung ist Adam Pritchards Markdown Cheatsheet.

Aufgepasst: Im Verzeichnis _site solltest du nichts von Hand anpassen, denn die Änderungen werden automatisch verworfen.

Für ein einheitliches Look & Feel haben wir einen einfachen Styleguide erstellt. Dieser ist nicht in Stein gemeisselt - du darfst gerne Änderungen vorschlagen!

Bevor du Änderungen am Layout und der Struktur der Webseite (3) vornimmst, solltest du das im Vorfeld mit uns besprechen! Am besten via Github Issues oder im persönlichen Gespräch.

Beispiel eines Beitrags

Folgende Schritt für Schritt Beschreibung eines Beitrags soll dir aufzeigen, wie du auch beitragen kannst. Konkret wird ein Tippfehler korrigiert.

1. Ich habe das Projekt lokal eingerichtet.

2. Ehe du Änderungen vornimmst, solltest du sicherstellen, dass die aktuellste Version ausgecheckt ist

   git checkout master
   git pull origin master

3. Ich erstelle und wechsle auf einen lokalen Branch

   git checkout -b fix-typo

4. Der Fehler ist auf der Unterseite Community (/community/). Anhand der Seitenhierarchie finde ich heraus, wo die betroffene Datei liegt: pages/community.md.

5. Ich öffne die Datei in meinem Editor.

6. Der Fehler ist dank der Suchfunktion schnell gefunden. Also schnell korrigieren!

7. Nun bin ich bereit zum Check-in. Als erstes stage ich die betroffene Datei:

   git add pages/community.md

8. Ich überlege mir eine kurze und aussagekräftige Commit-Message und mache den Commit:

   git commit -m "Fix typo in URL to statuten"

9. Ich pushe nun meine Änderungen auf Github:

   git push origin fix-typo

10. Nun bin ich bereit zum Pull-Request.
    Vorher gehe ich die Checkliste vor einem Pull-Request durch.

11. Auf der Seite meines Forks klicke ich auf Pull request:
    

12. Ich überprüfe folgende Punkte:

    1. Der Base Fork enspricht dem originalen Repository (openhsr/www.openhsr.ch) und der Base Branch ist master
    2. Der Head Fork enspricht meinem Repository und der korrekte Branch meines Repositories ist ausgewählt - hier also fix-typo
    3. Meine Änderungen können gemerged werden

    Los gehts (4)!
    

13. Ich schreibe eine kurze Beschreibung zu meine Pull request:
    

14. Der Pull request ist nun eröffnet! Hier können nun Code-Reviews / Diskussionen enstehen bevor der Commit gemerged wird.

15. Ist alles OK, so wird der Pull-Request gemerged - und damit ist mein Beitrag abgeschlossen:

Checkliste vor einem Pull-Request

• Ich habe alle Änderungen auf Rechtschreibefehler überprüft.
• In einem Pull-Request sind nur Änderung betreffend einer Sache (Bsp. Rechtschreibefehler oder ein neuer Tipp usw.).
• Meine Änderungen werden korrekt dargestellt.
• Das Generieren der Webseite gibt keine Fehler und Warnungen.

Projekt lokal einrichten

Um an der Webseite mitarbeiten zu können, benötigst du einen Github Account.

1. Benötigte Abhängigkeiten installieren
   Bevor du loslegen kannst, musst du Git, Make und Docker installieren:
   Git Jetzt installieren Make Jetzt installieren Docker Jetzt installieren

2. Forke das Projekt auf Github
   Gehe dazu mit dem Webbrowser auf das Repository www.openhsr.ch und klicke auf Fork:
   

3. Wenn du in einer Organisation bist, dann Forke das Projekt zu deinem Benutzer:
   

4. Du bist nun auf deinem Fork des Projekts. Kopiere die URL zum Repository:

5. Öffne ein Terminal, klone deinen Fork und wechsle in das Arbeitsverzeichnis:

   git clone <url-zum-fork>
   cd www.openhsr.ch

6. Das war es schon. Nun kannst du mit dem folgenden Kommando die Webseite bauen. Unter macOS muss make ohne sudo aufgerufen werden:

   sudo make

7. Du kannst nun mit dem Browser auf der Addresse http://localhost:4000 deine lokale Kopie der open\HSR Webseite aufrufen.

Wenn du nun Änderungen vornimmst, wird die Webseite automatisch neu generiert.

Wenn du genug hast, kannst du mit der Tastenkombination ctrl + c abbrechen.

Technischer Hintergrund

Die neue Seite des open\HSR ist im Gegensatz zu früher kein dynamisches Wiki, sondern eine mit Jekyll generierte statische Webseite.

Mehr Details zu Jekyll findest du auf der offiziellen Jekyll Webseite.

Die RubyGems werden über den Bundler verwaltet. Das Gemfile.lock lockt die Gems und Dependency auf spezifische Versionen. Wenn diese geupdated werden sollen kann man make updatedeps oder direkt bundle update im Docker Container ausführen. Im Gemfile sind sämtliche Gems aufgelistet und auf die Major-Version gelockt. Um einen Major-Update zu machen muss dies angepasst werden.

Um festzustellen, ob die Gems outdated sind oder bekannte Vulnerabilities dazu existieren, kann das Tool gemsurance verwendet werden. Am einfachsten installiert man es im Docker Container und führt es aus: gem install gemsurance && gemsurance. Dies erstellt eine gemsurance_report.html Datei, welche sämtliche Gems mit dem aktuellen Status auflistet.