Hilf dem CometVisu Projekt

Die Mitarbeit am CometVisu Projekt ist problemlos möglich und auch höchst willkommen! Hierbei sind nicht nur Entwickler angesprochen, die neue Features oder Bugfixes beitragen möchten, sondern auch Anwender, die ihre eigenen Erfahrungen in die Verbesserung der Dokumentation einfliessen lassen möchten.

Allgemeine Vorbereitungen

Grundsätzlich gibt es keinen Unterschied in der Vorgehensweise, zwischen Änderungen am Sourcecode und Änderungen an der Dokumentation, daher werden die Vorbereitungen dazu hier in allgemeiner Weise beschrieben. Die im folgenden beschriebenen Schritte müssen einmalig gemacht werden.

Sowohl der Sourcecode als auch die Dokumentation werden im offiziellen Github-Repository des CometVisu-Projekts verwaltet: https://github.com/CometVisu/CometVisu

Um Mitzuarbeiten braucht man also einen kostenlosen Account bei Github. Ist dieser erstellt, muss man das CometVisu-Projekt forken. Dazu führt man folgende Schritte aus:

  1. Auf github.com einloggen
  2. Auf diese Seite gehen https://github.com/CometVisu/CometVisu
  3. Auf den “Fork”-Button oben rechts klicken und den Anweisungen folgen

Damit hat man eine private Kopie des CometVisu-Repositories erstellt in dem man nach belieben eigene Ändungen vornehmen kann. Natürlich ist es einfacher, wenn man die Dateien auf seinem lokalen Rechner hat um sie dort bearbeiten zu können. Dazu muss man seine private Kopie des CometVisu-Repositories clonen. Zum lokalen Arbeiten mit den Dateien braucht man einen git client. Diesen gibt es z.B. für die Kommandozeile aber auch in diversen grafischen Ausführungen. Da die Vorgehensweisen und Begriffe bei allen Clients ähnlich sind, wird im weiteren Verlauf der Kommandozeilen-Client als Referenz benutzt. Zum ‘clonen’ des Repositories führt man folgende Schritte aus:

  1. Kommandozeile öffnen
  2. in einen Ordner gehen in dem der Unterordner des Projekts erstellt werden soll
  3. git clone https://github.com/<ihr-github-benutzername>/CometVisu.git (<ihr-github-benutzername> ersetzen durch den eigenen Benutzernamen)

das wars schon, die lokale Arbeitskopie liegt dann im CometVisu Unterordner. Damit sind alle Vorbereitungen getroffen.

Allgemeine Vorgehensweise

Wenn man nun eine Änderung durchführen möchte, sollte man sich an die hier beschriebene Vorgehensweise halten. Auch wenn Sie auf den ersten Blick unnötig kompliziert erscheinen, vor allem wenn man nur Kleinigkeiten ändern möchte. Die Erfahrungswerte zeigen, dass man auf Dauer weniger Probleme hat, wenn man sich immer an diesen Workflow hält und er damit zu Gewohnheit wird. Und so sieht der Workflow aus, zunächst als Übersicht ohne Details:

  1. Neuen branch erstellen
  2. die gewünschten Änderungen durchführen
  3. Änderungen im lokalen Repository speichern (das ist was anderes als “Datei speichern”)
  4. Die Schritte 2. + 3. können beliebig oft wiederholt werden, bis man der Meinung ist, das man alle Änderungen gemacht hat
  5. Änderungen ins private Github Repository laden
  6. beantragen, dass die Änderungen ins offizielle Repository übernommen werden

Und nun noch einmal dieselben Schritte im Detail:

  1. Auf Kommandozeile in das Verzeichnis mit dem lokalen Repository wechseln git checkout -b name-des-branches (Der Name des neuen Branches kann frei gewählt werden, es darf nur kein existierender sein)
  2. Die gewünschten Dateien mit einem Editor nach Wahl bearbeiten und speichern
  3. git commit -a -m "Kurze Beschreibung der Änderung" (Die Beschreibung nach Möglichkeit auf Englisch formulieren). Mit git status kann zunächst nochmal geprüft werden, welche Änderungen alle commited werden.
  4. s.o.
  5. git push
  6. Auf die Github-Seite des private Repositories gehen und auf new pull request klicken. Auf der folgenden Seite Comparing changes rechts neben dem Button head fork: <benutzername>/CometVisu findet sich der Button compare: <branch-name>. Drauf klicken und den Branch mit den Änderungen auswählen. Dann bekommt man nochmal eine Übersicht mit den Änderungen und kann auf den grünen Button namens Create pull request (grüner Button oben links) klicken. Dann kann man nochmal Beschreiben, welche Änderungen der Pull-Request beeinhaltet. In der Regel ist das aber bereits ausreichend vorausgefüllt und man kann durch klicken auf “Create pull request” (grüner Button unten rechts). Damit ist der Pull-Request erstellt

Jetzt muss man warten bis einer der Maintainer des CometVisu-Projekts des Pull-Request reviewed. Außerdem werden einige automatisierte Checks auf dem Pull-Request ausgeführt um mögliche Probleme zu erkennen. Sollte alles in Ordnung sein, wird der Pull-Request vom Maintainer gemerged und damit sind die Änderungen Teil des CometVisu-Projekts. Sollte der Maintainer Verbesserungsvorschläge haben, wird er dies durch Kommentare im Pull-Request tun. Ist dies der Fall, kommt nun der Vorteil des im Schritt 1. erstellen extra Branches zum Tragen. Man muss nähmlich nur die Schritte 2., 3. und 5. ausführen um die Korrekturwünsche des Maintainers auszuführen. Damit sind die Änderungen automatisch Teil des vorhandenen Pull-Requests.

Sind alle Änderungen abgestimmt und übernommen worden, kann der Branch gelöscht werden. git branch -D name-des-branches

Wenn man z.B. schon mit neuen Änderungen in einem neuen Branch begonnen hat, kann man beliebig zwischen den Branches hin und her wechseln und so sogar mehrere Pull-Requests und Änderungen gleichzeitig bearbeiten ohne diese inhaltlich zu vermischen. In einen anderen Branch wechseln kann man immer nach einem commit (siehe Schritt 3.) mit git checkout name-des-branches.

Repositories synchron halten

Über github.com

Um die von anderen Entwicklern gemergeden Änderungen mit dem eigenen Fork synchron zu halten, muss ein Pull-Request vom privaten Repository aus gemacht werden. In der Zeile This branch is ... commits ahead of CometVisu:develop. zeigt an, wieviele Änderungen seit der letzten Synchronisierung vorgenommen wurden. Direkt daneben befindet sich der Link zum Pull Request, welcher in der darauffolgenden Seite die Änderungen anzeigt, die in das private Repository gemerged werden können.

../_images/pull_request_sync.png

Pull Request für Synchronisation zwischen Haupt- und privaten Repository

../_images/github_sync2.png

Vergleich der Änderungen

Wichtig

Wichtig bei diesem Vergleich ist, dass der eigene base fork links und der offizielle head fork rechts steht.

../_images/github_sync3.png

Merge pull request erzeugen

Das Akzeptieren aller Änderungen synchronisiert die Änderungen vom Haupt-Repository auf das private Repository.

../_images/github_sync4.png

Merge bestätigen

../_images/github_sync5.png

Erfolgreiche Synchronisierung

Die lokale Kopie des privaten Repositories muss dann ebenso aktualisiert werden. Dazu muss im lokalen Repository in den Branch develop gewechselt werden (git checkout develop), dort werden alle abgestimmten Änderungen der Entwickler gemerged. Mit dem Befehl git pull erfolgt die Synchronisation zwischen lokalem und privatem Repository. Nachdem nun alle Repositories wieder synchron sind, kann wie oben unter 1. beschrieben mit neuen Änderungen an der Dokumentation fortgefahren werden.

Über die Kommandozeile

Natürlich kann man den lokalen Klon seines Repositories auch rein über Kommandozeilenbefehle komfortabel synchron halten. Um dieses möglichst einfach zu machen, muss man die Remotes seines lokalen Klons entsprechend konfigurieren.

Hinweis

Für die folgenden Beispiele wird angenommen, dass man den Usernamen gh-user hat und das CometVisu Repository über SSH geklont wurde (git clone git@github.com:gh-user/CometVisu.git). Wenn über HTTPS geklont wurde (https://github.com/CometVisu/CometVisu.git) sehen die URLs entsprechend anders aus.

Zusammenfassung

# aktuelle Einstellungen abfragen
git remote -v
>>> origin  git@github.com:gh-user/CometVisu.git (fetch)
>>> origin  git@github.com:gh-user/CometVisu.git (push)

# Aktualisierungen vom original Repository holen
git remote set-url origin git@github.com:CometVisu/CometVisu.git

# aktuelle Einstellungen prüfen
git remote -v
>>> origin  git@github.com:CometVisu/CometVisu.git (fetch)
>>> origin  git@github.com:gh-user/CometVisu.git (push)

# develop branch mit original Repository synchronisieren
git checkout develop
git pull

Ausführliche Vorgehensweise

Die aktuellen Einstellungen kann man mit dem Befehl git remote -v abfragen. Üblicherweise liefert das folgende Werte:

origin      git@github.com:gh-user/CometVisu.git (fetch)
origin      git@github.com:gh-user/CometVisu.git (push)

Das bedeuted, dass git beim Aktualisieren (fetch, pull) und auch beim pushen den Fork des Users auf github benutzt. Man möchte nun aber möglichst einfach Änderungen auf dem Haupt-Repository in den lokalen Klon laden. Dazu ändert man die fetch URL des remotes mit folgendem Befehl: git remote set-url origin git@github.com:CometVisu/CometVisu.git. Danach sollte git remote -v folgende Ausgabe liefern:

origin      git@github.com:CometVisu/CometVisu.git (fetch)
origin      git@github.com:gh-user/CometVisu.git (push)

Damit sind die Vorraussetzungen erfüllt und man kann seinen lokalen develop Branch (dieser enthält die neuesten Weiterenwicklungen) ganz einfach durch ein git pull aktualisieren.

Hinweis

Diese Vorgehensweise ist nur ratsam, wenn man nur an einem Rechner Änderungen an der CometVisu vornimmt. Wenn man gleichzeitig mehrere Rechner benutzt, muss man zwangsläufig die Änderungen die man von dem anderen Rechner in den eigenen Fork gepushed hat in den lokalen Klon bekommen. Dazu kann man ein zweites Remote einrichten mit git remote add fork git@github.com:gh-user/CometVisu.git und dann davon pullen git pull fork develop

Zu tun

  • weitere nützliche Git-Befehle (branches löschen, status, ...)
  • Merge-Konflikte
  • Ablauf-Diagramm für Workflow Änderung -> Pull-Request

Mithilfe bei der Dokumentation

Die CometVisu Dokumentation wird mit Hilfe des Sphinx - Python Documentation Generators erzeugt. Geschrieben wird die Dokumentation daher im reStructuredText-Format (kurz. RST). Hierbei handelt es sich um eine vereinfachte Auszeichnungssprache, die in der reinen Textform gut lesbar ist und den Vorteil hat, einfach in andere Formate umgewandelt zu werden [RST-Wiki] .

Zum tieferen Einstieg in die Syntax des RST-Formats sind folgende Links geeignet:

Eine allgemeine Einführung, welche sowohl die wichtigsten Grundlagen der Syntax liefert, als auch auf spezielle in der CometVisu Dokumentation benutzten Besonderheiten eingeht, soll jedoch dieser Abschnitt liefern. Mit dem Wissen dieses Abschnitts sollte es möglich sein, eigene Beiträge für die Dokumentation zu schreiben.

Zu tun

  • Lokales Erzeugen der HTML-Doku, inkl. Screenshots

Dokumentation schreiben mit VisualStudio Code

Der Editor Visual Studio Code bietet ein Plugin, mit dessen Hilfe man sich eine Live Preview der geschriebenen Dokumentation anzeigen lassen kann. Dazu muss zunächst der Editor installiert werden und darin die Extension restructuredtext (über den Menüpunkt Anzeigen -> Extensions suchen nach rst) installiert werden. Nach einmaligem Neuladen des Editors steht diese zur Verfügung.

Damit die Live Preview funktioniert muss Python installiert sein. Eine Anleitung um die nötigen Vorraussetzungen zu schaffen findet man hier: Install Sphinx

Ist alles korrekt eingerichtet, kann man eine RST-Datei aus der Dokumentation öffnen und mit Strg+Shift r das Live-Preview Fenster öffnen. Änderungen an der RST-Datei, sollten dann mit kurzer Verzögerung automatisch in Preview Fenster zu sehen sein.

../_images/visual_studio_live_preview.png

Ansicht des Editors mit Live-Preview

Mithilfe bei der Entwicklung

Zu tun

  • Beschreibung der Grundstruktur, wo was zu finden ist.
  • Einführung ins Build-Systemmit grunt
  • Style-Guide
  • JSDoc inkl. widget-examples
[RST-Wiki]https://de.wikipedia.org/wiki/ReStructuredText