TroLUG 2021-04#

Datum: 2021-04-01
Thema: Git auf Abwegen

Anmeldungen#

Jonas
Jan (Kann aber leider nur bis 20:20 wegen eines anderen Termins. Freut sich riesig.
Michael: Versuche mit Tablet von unterwegs zu sein. Leider ohne PC um Dinge direkt ausprobieren
Karl (Versucht dabei zu sein …hat es nicht geschafft. Danke für die super gute Dokumentation!)
Georg (heute in Pink :) ) Ich würd ja gerne mitlauschen, aber heute grätscht mir das THW, sorry.
Ansonsten: Vertrauen Sie auf die Versionskontrolle. Jjj
git revert, git rebase -i und git commit –amend sind meine Freunde!
Viel Spass Euch und friedvolle erholsame Osterfeiertage!\
Harald W.
Sandro (verspätet)
Jörg (verspätet … interressante links)

Protokoll#

Danke an Sebastian für den informativen und kurzweiligen Vortrag.

https://github.com/WBH-Project
https://gitahead.github.io/gitahead.com/
git-flavored Markdown: https://github.github.com/gfm/
GitHub Actions: https://github.com/features/actions
Set/unset Shell Optionen mit “set”: http://linuxcommand.org/lc3_man_pages/seth.html

Links
https://ohshitgit.com/

Euch allen schöne Ostertage.

Es Wurde sich die Projektdokumentation gewünscht. Anbei findet ihr den Text zu dem Projekt. Nutzt dies als Anreiz/Vorlage. Wichtig ist vorallem das sich jeder im Projekt abgeholt fühlt und die Arbeitsabläufe klar definiert sind. Sollte sich herausstellen das der Arbeitsablauf so nicht optimal ist, sollte man nachjustieren. Für kompliziertere Arbeitsschritte sind kurze Videos von Vorteil, so haben die Teammitglieder die Möglichkeit diese bei bedarf nochmal nach zu schauen und machen weniger Fehler aufgrund von falschem Stolz.

Die Toolchain von mir war GitAhead als grafisches Frontend für Git (dies ist nutzerfreundlicher für Giteinsteiger als die Konsole und senkt die Berührungsängste). Für die Editierung von Markdown kam Typora zum Einsatz, dies ist leider kein OpenSource Tool, macht das schreiben mit Markdown aber sehr angenehm. Man kann sich hier aber gerne mal Ghostwriter anschauen oder einfach VS-Code / VS-Codium verwenden.
Ansonsten habe ich mithilfe von Github Action, einem Pandoc-Latex Container und einem Shellscript die erstellung von PDF und TEX files automatisiert so das auch hier jeder mit den Tools arbeiten kann ohne viel Knowhow zu haben.

Toolchain:\

GitAhead https://gitahead.github.io/gitahead.com/
Typora https://typora.io/
- GhostWriter https://wereturtle.github.io/ghostwriter/
- VS-Code https://code.visualstudio.com/docs/languages/markdown
Github Actions https://github.com/features/actions
Pandoc-Latex Docker Container https://hub.docker.com/r/pandoc/latex
Shellscript

Projektdokumentation#

In der Projektdokumentation sind alle Dokumente zu finden welche für die erreichung der QB’s von nöten sind. Die Dokumente werden in einzelnen Ordnern abgelegt.

Arbeitssituation#

Wir sind ein Innovationsteam in einem großen Unternehmen welches sowohl eine Soft- und Hardware Sparte betreibt. In diesem Innovationsteam werden regelmäßig Projekte iniziiert um diese am Markt zu Prüfen und ggf. in das Produktportfolio zu integrieren. Der aktuelle Auftrag lautet “Konzeptionierung einer einfach zu nutzende Software zur Verwaltung eines Papierlosen Büros”. Die Software soll den Nutzer in das digitale Zeitalter führt und auf dem Weg begleitet, einfach zu bedienen und leicht in bestehende Strukturen integrierbar sein.

Background#

Das Unternehmen vertreibt unteranderem Hardware zur Digitalisierung von Dokumente und möchte nun auch in den Markt der Privatanwender und Kleinunternehmer expandieren. Bestehende Lösungen sind für diese Anwendergruppe zu teuer und zu komplex, weswegen ein Konzept für eine einfachere Softwarelösung, mit einem, für diesen Markt notwendigen, Funktionsumfang, erstellt werden soll.

Guideline#

Die Guidline soll eine einheitliche Bearbeitung ermöglichen und die Zusammenarbeit im Projekt stark vereinfachen. Im Anschluss an die Guidline finden sich ein paar nützliche Anwendungen und Links für weiterführende Informationen.

Kommunikation#

Zur allgemeinen Kommunikation sowie kurzfristigen Rückfragen und Absprachen wird Discord eingesetzt. Zusätzlich halten wir 1 bis 2 mal Wöchentlich eine Videokonferenz ab um den aktuellen stand zu besprechen und das Vorgehen zu planen.

Für anstehende Aufgaben werden Issues erstellt. Diese dienen auch zur Diskussion über das jeweilige Thema, Klärung von Fragen, Recherche, sowie Dokumentation von Entscheidungen. Damit können Arbeiten im Notfall übernommen und die Vorarbeit des anderen nachvollzogen werden.

Der Dateiaustausch findet überwiegend über Github statt, da die Dateien in der Regel das ganze Team etwas angehen. Sollten es nur Temporäre Dateien sein, so werden diese bitte über das DMS der WBH ausgetauscht oder Sebastian richtet hierfür einen Ordner in der Nextcloud ein.

Von der Verwendung von E-Mails ist ab zu sehen.

Arbeitsablauf und Zuweisung#

Wir sind ein Team und als solches sollten wir auch Aggieren. Wenn jemand eine Arbeit übernehmen möchte, dann kann er dies jeder Zeit tun in dem er sich den passenden Issue zuweist oder einen für die anfallende Arbeit anlegt. Damit ist es auch möglich die Arbeit untereinander zu kommentieren und am ende jemanden drüber schauen zu lassen, bevor der Issue geschlossen wird. Wenn notwendig oder sinvoll können Issues auch anderen Teammitgliedern zugewiesen werden, dies ist auch sinvoll wenn es Fragen zu klären gibt.

Ist das Issue einem Project zugeordnet (z.B. QB1) wird dieser Task automatisch auf “In Progress” gesetzt.

Github Workflow#

Für jedes Dokument im jeweiligen QB gibt es ein entsprechendes Issue und ein Branch welcher mit einem Großbuchstaben beginnt. Im QB2 wurden alle Dokumentenbranches neu angelegt und haben daher teils andere Namen als die alten Branches. Die neuen Branches sind nun auch für die restliche Zeit des Projektes gültig und werden immer nachgeführt.

Für jeden Branch an dem Änderungen vorgenommen werden, wird direkt mit dieser Änderung ein Pull-Request auf den Branch “finalisierung” erstellt. Der Pull-Request wird mit dem dazugehörigen Issue vorknüpft und dem jeweiligen QB zugeordnet. In dem Pull-Request wird direkt über das Dokument gesprochen, ab hier dient das Issue lediglich zur Dokumentation von Recherchen.

Ist das Dokument soweit fertig, wird über Github ein Review Request an ein anderes Teammitglied gestellt. Gerne kann auch über Discord kurz darauf aufmerksam gemacht werden. Gibt es vom zweiten Teammitglied nichts zu beanstanden wird der Review Approved. Es kann jedoch jeder zeit Kommentare von allen Teammitgliedern zu den Dokumenten im Pull-Request erstellt und über einzelheiten Diskutiert werden.

Ist ein Dokument Approved, so kann dies in den Finalisierungsbranch mit hilfe von “squash & merge” überführt werden. Sind alle Issues zum QB geschlossen, kann im Finalisierungsbranch noch nachträglich auftretene Fehler oder Anpassungen an das Dokumentendesign vorgenommen werden. In einem Abschließenden Meeting gehen wir gemeinsam die Dokumente durch und übernehmen diese am ende in den Main Branch. Dieser ist auch stand für die Abgabe der QB’s.

Zusammenfassung:

Issue anglegen für die anstehende Arbeit\
Issue sich selbst zuweisen\
Branch anlegen\
Dokument im Branch anlegen und einen Pull-Request erstellen\
Pull-Request mit Issue verknüpfen\
Arbeit starten und zwischenschritte commiten\
Im Pull-Request einen Review erbeten (oder über Discord)\
nach Prüfung übernahme (merge) in den Hauptbranch

Dokumentation#

Formate#

Für die Bearbeitung der Dokumente setzen wir Markdown ein, dieses lässt sich später einfach mit Hilfe von pandoc zu Latex, Word oder auch HTML konvertieren und ist sehr übersichtlich und nicht so ablenkend. Unsere Abgabe erfolgt dann jeweils in Form von PDF, diese sind am Portabelsten und sehen bei allen Nutzern gleich aus. Sollte es notwendig sein andere Tools an zu wenden (z.B. eine Tabellenkalkulation) so ist ein offenes Format zu verwenden (Open Document Format). Diese lassen sich sowohl in Microsoft Office als auch in jeder anderen Office Software öffnen und sollten in der Regel überall gleich formatiert dargestellt werden.

Ordnerstruktur#

Die Dokumente befinden sich jeweils in unterordnern, das liegt daran das für einige Punkte im QB mehrere Dokumente aus der gleichen Gruppe erstellt werden müssen. Wenn es sich um ein Dokument handelt heißt dieses README.md, bei mehreren wird in der README.md kurz beschrieben was in welchem Dokument zu finden ist. Sollten in den Dateien Grafiken eingebunden werden müssen so sind diese im jeweiligen Ordner in einem Unterordner “img” ab zu legen. Es kann bei einigen Dokumenten auch notwendig sein eine Quelle zu Zitieren, das jeweilige Dokument für die Quelle ist unter “bib” im jeweiligen Ordner ab zu legen.

-- Kosten
 |- bib\
 |- img\
-- Kommunikationsplan
 |- img\