Repository Umstellung (Vorschlag)

[sirjofri]

Hier mein Vorschlag:

• /README.md enthält die Schnittstellen-Beschreibung nach außen, also alles, was die App-Entwickler brauchen
• /License.txt obligatorische Lizenz. Gibt es ja schon
• /Contributing.md ist eine kleine Einführung für neue Schnittstellen-Entwickler, enthält Coding-Guidelines, Informationen zum Repository-Aufbau, ...; müssten im Detail natürlich noch geklärt werden
• /docs/ enthält die Schnittstellen-interne Dokumentation, könnten theoretisch auch via doxygen-(ähnliche) direkt aus der Code-Dokumentation erzeugt werden, je nach Bedarf.
• /docs/WS2017/ (bzw angepasst) für PDF-Dokumentation, sofern sie in das Repository sollen. Für die Schnittstelle relevante Informationen können ja in die restliche Dokumentation kopiert werden.
• /php/ (anderer Name?) enthält die tatsächlichen PHP-Skripte
• /setup/ enthält Dateien zur Einrichtung einer Entwicklungsumgebung (SQL-Dumps, ...)

Die Vorteile sind:

• Die App-Entwickler haben die von ihnen benötigten Informationen direkt verfügbar und müssen nicht das Repository durchforsten, bis sie alle Infos haben, die sie brauchen
• Die Dokumentation ist separat zum Code
• Die Dateien zur Einrichtung der Entwicklungsumgebung sind separat zum Code
• Dokumentation kann (im Falle von Markdown-Dateien) untereinander verlinkt werden
• Dokumentation kann (...) auch als plain-text gut gelesen werden
• Dokumentation ist (...) einfach zu schreiben
• Dokumentation ist (im Falle von doxygen) generierbar, Dokumentationsorganisation im Code

Zur Coding-Organisation ist mein Vorschlag:

• master-Branch enthält den aktuell laufenden Stand, wie er auf dem Server abgebildet ist
• testing-Branch enthält den geplant-künftigen Stand, wird beim Update in master gemergt und für kleinere Veränderungen direkt benutzt. Dieser Branch wird auch auf dem Testserver genutzt
• mehrere development-Branches (mit sprechenden Namen) werden für größere Entwicklungs-Schritte genutzt und zum Testen der entwickelten Features verwendet. Diese verschiedenen Features werden in testing gemergt und zusammen getestet und letztlich (bei Bestehen des Testes) in master gemergt. Nur noch einen development-Branch zum Testen und entwickeln. Weitere Branches bei Bedarf, z. B. größeren Veränderungen.

Damit haben wir ein regelrechtes Staging, wie es auch aus anderen Software-Projekten bekannt ist (allerdings in etwas abgespeckter Version). Die einzelnen Entwicklungsschritte Versionen werden in master zusätzlich als Tags gekennzeichnet (mit git tag).

[cpfeiffer94]

• Viele Studierende müssen für ihre Studienarbeiten bzw. Projektarbeiten Dokumentationen in anderen Programmen bzw. Tools schreiben, damit diese dann zur Bewertung gedruckt bzw. als PDF abgegeben werden können, hier ist eine Doku die nur in Plain Text verfügbar ist problematisch. Eine Art Quick Start Guide bzw. eine Übersicht über die Funktionalität der Schnittstelle in deiner vorgeschlagenen Form finde ich aber ergänzend auch sinnvoll (auch wenn das dann zusätzlich zur Doku mehr Aufwand bedeutet). Nachdem du keine Studienarbeit oder Projektarbeit dieses Semester schreibst, kannst du aber gerne auf die von dir genannte Art der Dokumentation zurückgreifen :-)

• Ich finde wir sollten die Dokumentationen für alle Repositorys in dem Design Branch sammeln und den Design Branch dementsprechend als Doku und Design Branch betiteln. So müsste man einerseits weniger Daten beim erstmaligen Pullen jedesmal herunterladen. Andererseits wären alle Dokumentationen zu allen Repositorys an einem Ort leicht auffindbar und es wäre für Neulinge leichter die Entwicklungen der vergangenen Semester anhand nachzuvollziehen. Auch würden sich die Dokumentationen nicht auf verschiedenen Branches verteilen.

• Deine Vorschläge zur Code Organisation machen auch Sinn, jedoch glaube ich dass man das Ganze aktuell auf zwei Branches reduzieren könnte: master und development .

[sirjofri]

• Natürlich steht an einer Hochschule auch das Lernen im Vordergrund, und es stellt grundsätzlich kein Problem dar, auch PDF-Dokumentationen in die Verzeichnisse einzubeziehen. Das wird zwar unübersichtlicher, ist aber machbar und nicht so schlimm.
• Mit dem Design-Branch meinst du bestimmt das Schwester-Repository. Natürlich wäre das einfach, alles da "rüberzuschaufeln", die Vorteile einer gemeinsamen Dokumentation in einem Repository liegen auf der Hand, die Problematik ergibt sich aus der Versionierung. Da Dokumentation eng mit dem Code/der Funktionalität verwandt ist (um nicht zu sagen: Sie sind eine Einheit) macht es auch Sinn, die Dokumentation logisch (bzw temporal) mit dem Code zu verbinden. Indem man die Dokumentation gleichermaßen mit dem Code an die neuen Bedürfnisse anpasst stehen sie zusammen in der Historie, was im Falle von Rollbacks deutlich einfacher ist (automatisch passiert), was bei einem getrennten Repository schwieriger ist (Versionsnummern und manuelles "auseinanderklamüsern").
• Die Dokumentation ist einfacher zu warten, wenn sie mit dem Code verheiratet ist. Es ist nämlich einfacher, ein Repository aktuell zu halten als zwei.
• Das Daten-herunterpullen mit Dokumentation sehe ich auch ein. Dafür ist eigentlich vorgesehen, das etwas versteckte Wiki-Repository, das zu jedem Repository existiert, zu verwenden. Damit kann man Wiki und Code sauber trennen. Ich finde jedoch (persönliche Meinung), dass das Wiki ausschließlich für die Schnittstellendokumentation ist, nicht für die Codedokumentation der Schnittstelle. Natürlich spricht nichts dagegen, die Verwendung an unsere Bedürfnisse anzupassen.
• Der Vorteil von Dokumentationen im jeweiligen Repository ist auch, dass man üblicherweise weiß, welche Dokumentation man sucht. Ob man nun in einem externen Repository in einen Unterordner nachschaut oder in dem jeweiligen Repository direkt macht demnach kaum Unterschied. Natürlich bietet sich an, die Repositories in diesem Punkt ähnlich aufzubauen.
• Wichtig ist, zwischen 2 Dokumentationen zu trennen: Es gibt eine Schnittstelle-Dokumentation, die für die App-Entwickler gedacht ist (was will die Funktion, was bekomme ich zurück); es gibt aber auch die Code-Dokumentation (welche internen Funktionen habe ich, die niemand sieht? Wie funktionieren die?). Diese sollten sauber getrennt werden, weil die App-Entwickler nicht zu wissen brauchen, wie unser Code funktioniert. Ihnen ist nur die Funktionalität der Schnittstelle selbst wichtig (Kapselung). Ich vermute jedoch, dass das im Fall von Studienarbeiten/Projektarbeiten schwierig bis unmöglich ist.
• Wegen der Branches bin ich weiterhin der Meinung, dass für größere Veränderungen, die mehrere Commits benötigen, ein eigener Branch praktisch ist. Der kann danach ja wieder gelöscht werden, wenn er gemergt wurde. Einen Grund dafür haben wir erlebt: Ich arbeite an einem größeren Projekt, das längere Zeit in Anspruch nimmt, du machst eine kleine Veränderung, die meine Arbeit zu diesem Zeitpunkt erschwert. Wenn wir auf dem selben Branch gearbeitet hätten, würdest du dir bei deiner kleinen Änderung schwerer tun, weil du meinen Code noch nicht kennst, ich wiederum müsste dann erst einmal überblicken, was du geändert hast. Ich glaube du verstehst, warum ich es als notwendig erachte, Branches grundsätzlich offen zu lassen.
• Mit dem Testfeature von GitHub habe ich noch nicht gearbeitet, man kann sich das natürlich genauer anschauen (Continuous Integration ist immerhin mega praktisch). Es ersetzt jedoch nicht die Tests in einer möglichst End-nahen Testumgebung.

[cpfeiffer94]

• Mit anzumerken ist, dass Dokus oftmals erst am Ende des Semesters geschrieben werden. Schnittstellenerweiterungen war meistens nur eine Zugabe zu anderen Studienarbeiten.

• Ja ich meine das Design Repository... Hier war ich unachtsam beim schreiben

• Meine Anregung war, die PDF Dokumentationen in den Design Repository zu legen. Diese werden 1x im Semester hochgeladen (am Ende) und dann nicht mehr verändert, weil die Studienarbeit ja abgegeben wurde.

• Branches kosten uns nichts, von daher habe ich eigentlich auch kein Problem wenn Du vor dem Testing Branch erst nochmal in einem eigenem Branch arbeiten möchtest. Das kann auch das Push Notification Team machen.

[cpfeiffer94]

Nach gemeinsamer Diskussion, hat @avinotec (Michael Stepping) folgende Vereinbarungen festgelegt. (Die obigen Kommentare habe ich, Michael Stepping, soeben - sinnvoll - gekürzt.)

Namenskonventionen und Branches - generell:

• master Branch: aktueller Stand des Codes, der auf dem App-Server produktiv ist. Ein Testserver sollte damit jederzeit bestückt werden können.
• dev_xxx : Development Branch. Entwicklungen der jeweiligen Grupppen.

Dokumentation in der Schnittstelle:

• Auch Übersicht was in einem Repository passiert (Einstiegsdokumentation bzw. Dokumentation für externe)
• Schnittstellenentwickler Doku
• App Entwickler Doku
• Generelle Überblicksdoku und alle Dokumentationen, die App/Betriebssystem-übergreifend sind.
• Bei den Push-Notifications sind aber die jeweiligen Betriebssysteme die Treiber, daher dort die detaillierten Dokumentationen. Für PHP nur der entsprechende (zentrale) Teil.
• Dokumentationen (Schnittstelle, Appdoku) sollen in ihren Repositories bleiben.

Designbranch:

• In den Design Branch sollen Unterlagen, die zum Layout (Corporate Design), Rechtliches und für die Entwicklung unwesentliches abgelegt werden. Dokumentationen (Schnittstelle, Appdoku) sollen in ihren Repositories bleiben.

Schnittstellenwiki:

• Die Schnittstellen Wiki Dokumentationen soll zukünftig die App Entwickler Dokumentation sein -> Umziehen!
• Schnittstellenwiki soll nicht fortgeführt werden und zukünftig leer sein

Ordnerbenennungen:

• Dokumentationen -> docs
• MySQL -> mysql -- Dump, initiales Setup und initiale Befüllung, Spaltennamen, --> setup -- Dumps für Test -> data
• PHP Skripte, alle. -> php

[sirjofri]

Wie sieht das jetzt konkret aus, @jofranz, wo sollen letzten Endes die ganzen FCM-Scripts hin? in den php-Ordner? #13 #14

Michael Stepping: --> Alle PHP Skripte in /php ....

[sirjofri]

Zur Vollständigkeit noch die Datenbank-Dateien:

• tables.sql - Create Table-Anweisungen
• func.sql - Stored Procedures, Funktionen, ...
• views.sql - Views (vorerst leer)
• database.sql - Datenbank selbst einrichten
• migration.sql - Anpassungen bei Update
• testdata.sql - Testdaten zum Füllen in einer Testumgebung

Im übrigen schlage ich mich nicht darum, alles selbst zu machen.

[avinotec]

views.sql können wir anlegen, und noch leer lassen. Es werden welche kommen werden.

Alle PHP Dateien, egal ob FCM oder iOS in das Unterverzeichnis PHP. Das ist dann der Stand, den wir auch auf dem Produktivserver haben.