Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- fn2:aktualisierung [2018/08/31 15:35] – [Link zum GitLab-Server] rsauer
+++ fn2:aktualisierung [2024/03/04 14:54] (aktuell) – [(SQL-)Skripte zur Aktualisierung der Datenbankstrukturen] christoph
@@ Zeile 1: / Zeile 1: @@
-====== Dokumentation zum Aktualisierungsprozess von fn2Web ======
+====== Aktualisierungsprozess von fn2Web ======
-===== Aktualisierungsprozess von fn2Web =====
+==== Versionierung, Releases und Updates für fn2Web ====
-==== Releasezyklus, Patches und Hotfixes für fn2Web ====
+fn2Web ist nach dem Schema <fn2Web-Version>.<Release>.<Update> versioniert. Die Versionsnummer \\
+.04.05.032
+beschreibt zum Beispiel die fn2Web-Version 2.04, das Release 5 und das Update 32.
-**Releases** von fn2Web sollen zukünftig zweimal jährlich, im Januar und im Juli, veröffentlicht werden. Begonnen wird mit dem Release //r17.07//. Für die Releases werden Release Notes zur Verfügung gestellt. Darin enthalten sind alle erledigten Tickets sowie die erforderlichen Änderungen, die in den Konfigurationsdateien von der fn2Web-Installation vorgenommen werden müssen.
+**fn2Web-Version**\\
+Die fn2Web-Version wird nur bei grundlegenden, tiefgreifenden Änderungen im System fortgeführt, was nur sehr selten der Fall ist.
-Zukünftig sollen **Patches** für fn2Web jeden Montag einer geraden Kalenderwoche bis <del>13:00</del> 14:00 Uhr zur Verfügung gestellt werden. Stehen zu diesem Zeitpunkt keine Aktualisierung zur Verfügung, wird folglich kein Patch bereitgestellt. Bei diesen Patches handelt es sich um kleinere Erweiterungen. Dies sind dann in der Regel Features, die von einer Hochschule benötigt werden und nur einen begrenzten Bereich betreffen. Zu jedem Patch gibt es einen Eintrag in den Patch Notes. In chronologischer Reihenfolge wird ab dem Zeitpunkt des Releases dokumentiert, welche Tickets darin gelöst worden sind und ob Änderungen an den Konfigurationsdateien erforderlich sind. Es muss immer der aktuelle Patch eingespielt werden. Wurde beim Einspielen des Patches das dazugehörige Release noch nicht installiert, müssen auch die Release Notes berücksichtigt und die darin enthaltenen Anweisungen ausgeführt werden.
+**Releases**\\
+Releases werden von uns grob zwei Mal im Jahr geplant, zum Jahres-Anfang und im Herbst. Optional können bei Bedarf zusätzliche Releases veröffentlicht werden, z.B. wenn ein schwerer Fehler im System eine zeitnahe Aktualisierung bedingt. Releases beinhalten aufwändigere Erweiterungen und Anforderungen und verlangen häufig das Anpassen von hochschulspezifischen Konfigurationsdateien.
+Obwohl ein neues Release so schnell wie möglich eingespielt werden sollte, ist uns bewusst, dass das aufgrund des hohen Test-Aufands nicht immer möglich ist. Daher versorgen wir sowohl das aktuelle, als auch das vorhergehende Release mit Updates.
+{{ :fn2:releasezyklus.png?direct&300 |}}
+Die Termine für Releases und Updates sind absichtlich etwas vage gehalten. Die dadurch erlangte Freiheit ermöglicht es uns zeitnah und agil auf die Bedürfnisse unserer Kunden eingehen zu können.
+**Updates**\\
+Updates sind meist kleinere Erweiterungen und dringende Fehlerbehebungen, die von uns zeitnah veröffentlicht werden. Es ist nicht zwingend notwendig, fn2Web immer auf dem neuesten Update-Stand zu halten. Dennoch sollten die [[releasenotes:|Release Notes]] aktiv gelesen werden, da mit Updates auch kritische allgemeine Fehler behoben werden. Eine viel genutzte best practice ist auch im [[http://tickets.ihb-eg.de|Ticketing-System]] die neuesten erledigten Tickets im Auge zu behalten oder, bei Problemen, dort erst ein mal stichpunktartig zu suchen.
-Daneben werden **Hotfixes** zeitnah zur Lösung eines über das Ticketsystem gemeldeten Problems zur Verfügung gestellt.
 ==== Releasezyklus für fn2Module ====
-Der Releaseprozess für die fn2Module ändert sich nicht. Neue Versionen, die von Kunden angeforderte Features enthalten, werden nach Fertigstellung bereitgestellt. Die in den neuen Versionen enthaltenen Änderungen sind in den dazugehörigen Release Notes dokumentiert.
+Der Releaseprozess für die fn2Module ändert sich nicht. Neue Versionen, die von Kunden angeforderte Features enthalten, werden nach Fertigstellung bereitgestellt. Die in den neuen Versionen enthaltenen Änderungen sind in den dazugehörigen [[releasenotes:|Release Notes]] dokumentiert.
 ==== Gegenseitig abhängige Updates von fn2Module und fn2Web ====
@@ Zeile 24: / Zeile 36: @@
 Sowohl für fn2Module als auch für die Komponenten von fn2Web gibt es SQL-Skripte. Diese **müssen** eingespielt werden.
-Dateien mit den Skripten für die drei verschiedenen Datenbanken finden sich auf dem ftp-Server. Bitte suchen Sie selbst die passende Variante heraus. Achten Sie darauf, dass Sie Skripte lückenlos einspielen. Dabei hilft die eindeutige Skript-Nummer. Achten Sie auch darauf, jedes Skript mit "commit;" abzuschließen, sofern kein  Autocommit eingestellt ist. Sollte ein Skript eine längere Laufzeit haben, brechen Sie es **nicht** ab, auch wenn damit "nur" ein Default-Wert gesetzt wird.
+Dateien mit den Skripten für die zwei von uns unterstützten Datenbanken (Oracle DB und PostgreSQL) finden sich auf dem ftp-Server. Bitte suchen Sie selbst die passende Variante heraus. Achten Sie darauf, dass Sie Skripte lückenlos einspielen. Dabei hilft die eindeutige Skript-Nummer. Achten Sie auch darauf, jedes Skript mit "commit;" abzuschließen, sofern kein  Autocommit eingestellt ist. Sollte ein Skript eine längere Laufzeit haben, brechen Sie es **nicht** ab, auch wenn damit "nur" ein Default-Wert gesetzt wird.
 Es kann vorkommen, dass Sie selbst Werte im Skript eintragen oder ergänzen müssen. Beachten Sie dazu die Hinweise in den Kommentaren.
 Bei Rückfragen wenden Sie sich zunächst an die im Skript angegebene Ansprechperson. Sollte ein Problem auftreten, das mehrere User betreffen könnte, eröffnen Sie bitte ein Ticket in dem entsprechenden Bereich SQL-Skripte unseres Ticketing-Systems
-===== GIT zum Download der Releases =====
-GIT ist eine freie Software zur verteilten Versionsverwaltung und kann [[https://git-scm.com/|hier]] für alle gängigen Plattformen heruntergeladen.
+===== git zum Download fn2Web-Versionen =====
-Eine Übersicht zahlreicher grafischer Oberflächen für GIT gibt es unter [[https://git-scm.com/downloads/guis| hier]]. Die Verwendung einer grafischen Oberfläche ist aber nicht zwingend erforderlich, da alle benötigten Befehle in diesem Wiki beschrieben werde. Wir selbst nutzen neben der Kommandozeile [[https://www.sourcetreeapp.com/|SourceTree von Atlassian]]. Das Programm ist sowohl für Windows als auch für Mac verfügbar.
+git ist eine freie Software zur verteilten Versionsverwaltung und kann [[https://git-scm.com/|hier]] für alle gängigen Plattformen heruntergeladen.
-Ein Grundlagenbuch ist [[https://git-scm.com/book/de/v1|hier]] frei verfügbar. Einen tieferen Einblick in die Syntax von GIT-Befehlen erhalten Sie in der offiziellen [[https://git-scm.com/doc|Dokumention]].
+git verwaltet Änderungen (**Commits**) und gliedert diese in Zweige (**Branches**), die von einander abgezweigt und zusammen geführt werden können. Alle Branches zusammen genommen werden als ein **Repository** bezeichnet. Ein git-Repository existiert immer erst einmal für sich lokal, wobei einzelne Branches mit den Zweigen eines anderen Repositories verknüpft werden können. Andere Repositories können bei einem lokalen Repository als sog. **Remotes** hinterlegt werden.
-===== Übersicht über die Zusammenhänge beim neuen Release-Mechanismus =====
+Eine Übersicht zahlreicher grafischer Oberflächen für git gibt es [[https://git-scm.com/downloads/guis| hier]]. Die Verwendung einer grafischen Oberfläche ist allerdings nicht zwingend erforderlich, da alle benötigten Befehle in diesem Wiki beschrieben werden. Ein Grundlagenbuch ist [[https://git-scm.com/book/de/v1|hier]] frei verfügbar. Ein tieferer Einblick in die Syntax von git-Befehlen kann in der offiziellen [[https://git-scm.com/doc|Dokumention]] erlangt werden.
-{{ :fn2:release_vorgang_git.png?nolink |}}
+fn2Web kann von unserem [[https://gitlab.ihb-eg.de|GitLab-Server]] bezogen werden. Grundsätzlich gibt es zwei Möglichkeiten das fn2Web-Repository herunter zu laden, die im Folgenden beschrieben werden:
+==== Direkter Download von fn2Web (nicht empfohlen) ====
+Das Repository und auch einzelne Dateien können dirkt über die GitLab-Oberfläche in verschiedenen Formaten gepackt herunter geladen werden.
+{{ :fn2:gitlab_downloaddirekt.png?direct |}}
+Da hierbei sämtliche Vorteile, die git bietet, ignoriert werden, sollte so nur in Ausnahmefällen vorgegangen werden.
-===== fn2Web-Releases Verzeichnisstruktur =====
+==== Verknüpfung mit einem lokalen git-Repository (dringend empfohlen) ====
+Der wesentlich elegantere und ganzheitlichere Weg fn2Web zu beziehen ist ein lokales git-Repository mit dem fn2webapps-Repository auf dem GitLab-Server zu verknüpfen.
-Mit dem nachfolgenden Screenshot wird die Verzeichnisstruktur, die man beim Download von fn2Web-Releases erhält, erklärt.
+Im Folgenden werden die jeweiligen Konsolen-Befehle benutzt. Es gibt zahlreiche grafische Tools für git, die im Grunde alle das gleiche können, da sie auf eben exakt jene Befehle zurückgreifen. Hier auf einzelne Tools ein zu gehen würde den Rahmen dieses Wiki-Eintrages sprengen.
-{{ :fn2:fn2web-releases_verzeichnisstruktur.jpg?nolink |}}
+**Ersteinrichtung**\\
+Initialisierung (Erstellen) eines lokalen git-Repositories:
+  git init
+erstellt einen Ordner .git/ im aktuellen Verszeichnis (für fn2Web-Zwecke sollte dieses Verzeichnis leer sein) in dem sich die Verwaltungsdateien für das Repository befinden.
-===== Wichtige GIT-Befehle =====
+Verknüpfen des Repositories mit dem fn2webapps-Repository über eine Remote:
+  git remote add fn2web https://gitlab.ihb-eg.de/fn2/fn2webapps.git
+erstellt eine Remote mit dem Namen "fn2web" und verknüpft diese mit dem fn2webapps-Repository.
+  git fetch fn2web
+läd die Informationen zur Remote "fn2web" herunter. Es werden noch keine Dateien erstellt.
-==== Zum erstmaligen Download der FN2-Webapps ====
+  git checkout -b 2.04.06 fn2web/2.04.06
+erstellt einen neuen lokalen Branch "2.04.06", verknüpft diesen mit dem Branch 2.04.06 im fn2webapps-Repository und checkt ihn aus, d.h. es werden die tatsächlichen Dateien, wie sie im Branch hinterlegt sind, erstellt. Die Ersteinrichtung ist damit abgeschlossen.
-<code>git clone https://<BENUTZERNAME>:<PASSWORT>@gitlab.ihb-eg.de/fn2/fn2webapps.git</code>
+Mit
+  git log
+kann überprüft werden, auf welchem Stand sich der Branch befindet (genauer gesagt können so die Commits des Branches betrachtet werden).
-Der Befehl "git clone" kopiert die Ablage in einen neu erstellten Ordner und erstellt einen remote-tracking Zweig für jeden Zweig in der originalen Ablage.
+**Aktualisierung**\\
+Das Aktualisieren des momentan ausgecheckten Branches ist denkbar einfach:
+  git pull
-Während des Klonens kann mehrfach die folgende Fehlermeldung auftreten:
+Soll auf ein neues Release aktualisiert werden, ist dieses im fn2webapps-Repository als ein eigener Branch vorhanden (Branch "2.04.05" ist Release 5, Branch "2.04.06" ist Release 6, etc.). Es muss lediglich ein
-<code>error: RETR response: 550 (curl_result = 78, http_code = 550, sha1 = 98120a75125204713db511227718579caea88aa6)</code>
+  git fetch
-Diese bitte ignorieren und den Klon-Vorgang bis zum Schluss durchlaufen lassen.
+ausgeführt werden, um das lokale Repository mit der remote abzugleichen und anschließend ein
+  git checkout -b [neuer Branch] fn2web/[Release]
+gemacht werden um den neuen Branch lokal an zu legen. Falls der Name des gewünschten Branches mit einem '#' beginnt, muss er in Anführungszeichen gesetzt werden.
-<WRAP center round important 60%>
+Danach müssen nur noch die aktualisierten Dateien in das Webapplikationsverzeichnis des Servers kopiert werden. Dies kann über unsere mitgelieferten Kopierskripts (Achtung, müssen angepasst werden!), oder auch gerne durch andere Mechanismen geschehen.
-In dem ausgecheckten Verzeichnis dürfen niemals vorhandene Dateien geändert werden!
-</WRAP>
-==== Laden von Updates des aktuellen Zweiges ====
+<WRAP center round important>
+Der FTP-Server ist für git nicht mehr verfügbar und wurde von einem GitLab-Server abgelöst.
+Deshalb muss in der Datei ''/.git/config'' für die fn2web-Remote die URL ''https://gitlab.ihb-eg.de/fn2/fn2webapps.git'' hinterlegt sein (ggf. mit Nutzer und Passwort). Zum Beispiel:\\
-Um zu prüfen, ob neue Zweige oder Updates zur Verfügung stehen, ist <code>git fetch --all -v</code> einzugeben.
+<code>[remote "fn2web"]
+	url = https://gitlab.ihb-eg.de/fn2/fn2webapps.git</code>
+für die Remote "fn2web".
+</WRAP>
-Mit <code>git pull</code> wird automatisch zum aktuellsten Stand des Zweiges gesprungen. Dazu werden alle Neuerungen geholt. <WRAP center round important 60%>Um das problemlos zu ermöglichen, dürfen vorhandene Dateien niemals geändert werden!</WRAP>
-Um anzuzeigen, **welche Zweige existieren**, gibt man den Befehl <code>git branch</code> ein. Mit * in der Ausgabe ist markiert, auf welchem Zweig man sich befindet.
-Zu einem anderen Zweig kann gewechselt werden mittels des Befehls <code>git checkout ZWEIGNAME</code> Dabei beachten, wenn der Name des Branches mit einen **#** beginnt, diesen Namen in einfache Anführungszeichen setzen. Beispiel: <code>git checkout '#3563'</code>
-Um die komplette Historie anzeigen zu lassen, wird der Befehl <code>git log --graph --decorate --oneline --all --since="2015-10-01"</code> eingegeben. Um anschließend einen älteren Zustand wiederherzustellen, geben Sie folgenden Befehl mit dem Label des commits ein der zu dem gewünschten älteren Zustand passt. <code>git checkout <commit label></code> Die Markierung **(HEAD)** zeigt einem an, wo man sich gerade befindet.
-**Die Ausgabe ist wie folgt zu lesen:** //Label des Commits// (//HEAD// -> dieser Zustand ist augecheckt, //origin/...// -> Name und Zweig des entfernten Rechners (auf dem FTP-Server), //origin/HEAD// -> dieser Zustand ist auf dem entfernten Rechner ausgecheckt, //Name des Zweiges//)
-==== Wartung: verwaiste Zweige löschen, um Speicherplatz frei zu geben ====
-Dieser Befehlt, löscht einen lokalen Zweig - üblicherweise, wenn eine Auslieferung zum Testen nicht mehr benötigt wird und Speicher freigegeben werden soll.
-<code>git branch -d <branchname></code>
-Mit diesem Befehl werden die Zweige die auf dem Server bereits gelöscht wurden, bereinigt <code>git remote update --prune</code>
+<WRAP center round important>
+Es ist leider eine gängige Praxis bei Linux-Systemen (und in geringerem Umfang auch Windows) standartmäßig mit dem Superuser zu arbeiten. In Zeiten von Emotet und ähnlicher Schadsoftware, die auch schon einige Hochschulen befallen haben, sollte es überflüssig sein zu erläutern, wieso das generell eine schlechte Idee ist. Hier ein weiterer Grund:\\
+Wenn mit dem root-User git-Operationen ausgeführt werden, dann werden die Änderungen im .git-Ordner auch mit dem root-User als Inhaber hinterlegt. Ein normaler Nutzer kann dann diese nicht mehr ändern ohne die git-Befehle selbst unter Superuser-Kontext auszuführen. Je nach Art der Änderungen wird das dem Nutzer aber von git nicht mit geteilt. In anderen Worten: es kann dadurch passieren, dass ein 'git pull' ohne Fehlermeldung durchläuft, jedoch keine oder nicht alle Dateien aktualisiert werden. Daher noch einmal:\\
+<WRAP center>**Bitte, wiederstehen Sie der 'sudo -s'-Versuchung.**</WRAP>
+</WRAP>
 ==== Aktualisieren der FN2-Installation ====
@@ Zeile 94: / Zeile 113: @@
 Im Ordner Konfigurationsdateien gibt es Skripte für Windows (//CopyFN2-Webapps.cmd//) und Linux (//CopyFN2-Webapps.sh// und //fn2excl.txt//). Bitte diese als Kopiervorlage verwenden und in den Skripten die gewünschten Variablen setzen bzw. die auszuschließenden Ordner als solche markieren.
+Anschließend müssen alle Einträge und Änderungen in den Hochschul-spezifischen Dateien vorgenommen werden, die seit dem letzten Update hinzugekommen sind. Daher, die [[releasenotes:start|Release Notes]] müssen vom alten bis zum aktuellen Stand durchgegangen und die Änderungen übernommen werden. Da das bei vielen Änderungen ein sehr aufwändiger und zeitraubender Prozess sein kann, empfehlen wir Updates möglichst häufig aufzuspielen um Fehler zu vermeiden.
+===== fn2Web-Releases Verzeichnisstruktur =====
-==== Wechseln eines Zweiges und anzeigen von Release-notes ====
+Mit dem nachfolgenden Screenshot wird die Verzeichnisstruktur, die man beim Download von fn2Web-Releases erhält, erklärt.
-Zu einem anderen Zweig kann gewechselt werden mittels des Befehls <code>git checkout ZWEIGNAME</code>
+{{ :fn2:fn2web-releases_verzeichnisstruktur.jpg?nolink |}}
-Der Befehl <code>git checkout <commit hash></code> wechselt zu einem früheren Zustand des Zweiges.
+===== Wichtige GIT-Befehle =====
-Die <commit hash> werden mit dem Befehl <code>git log</code> oder mittels <code>git log --pretty=format:"%ar - %cd - %H - %an - %s" --since="2015-10-01" --graph --date=short</code> angezeigt. (Weitere Dokumentation zur Ausgabe gibt es [[https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History|hier]].).
+  git fetch --all -v
+aktualisiert die lokalen Informationen zu den bekannten Remotes und gibt Änderungen detailiert an. Im Endeffekt kann so überprüft werden ob neue Releases und Updates veröffentlich wurden.
-Die Release-Notes können mit demselben Befehl <code>git log</code> angezeigt werden und mittels <code>git show</code> werden die Release-Notes und die durchgeführten Änderungen dargestellt.
+  git pull
+führt eigentlich zwei separate Befehle aus: 'git fetch' und 'git merge'.\\
+Fetch wurde bereits beschrieben, Merge führt lokal eingepflegte (commitete) Änderungen mit denen des Remote-Branches zusammen. Wir möchten Sie bitten, darauf zu verzichten lokal Änderungen ein zu pflegen. <wrap important>Wir übernehmen weder Garantie, noch Support, für derartige Änderungen. Bitte sprechen Sie solche Eingriffe mit uns ab!</wrap>
-Mit den folgenden Befehlen, können die release-notes in verschiedenen Formaten dargestellt werden.
+  git branch
+zeigt die lokalen Zweige/Branches an und markiert den aktuell ausgecheckten.
-<code>git log --format=oneline</code>
+  git remote -v
+zeigt die lokal definierten Remotes und zugehörige URLs an.
-<code>git log --format=short</code>
+  git log
+  git show
-<code>git show --format=short</code>
+sind beides Befehle, mit denen eine Übersicht über den Verlauf von Commits im Repository gewonnen werden kann.
-Der Befehl <code>git status</code> zeigt an, auf welchem Zweig man sich befindet.
+Die meisten git Befehle leisten viel mehr, als hier aufgeführt werden kann. Daher sei auch hier nocheinmal auf die [[https://git-scm.com/docs/|git-Dokumentation]] und ihre (sehr gute und hilfreiche) Suchfunktion verwießen.
 ===== Troubleshooting =====
-==== Wenn der Hinweis ignoriert wurde und vorhandene Dateien geändert wurden, ist folgendes durchzuführen: ====
+==== Wenn vorhandene Dateien geändert wurden, ist folgendes durchzuführen: ====
-Ein Update wird dann mit dem Hinweis abbrechen, dass lokale Änderungen durch das Update überschrieben würden und man diese entweder committen (was von FlexNow-Seite aus nicht erwünscht ist) oder diese "Stashen" soll. In diesem Fall ist ein Stash durchzuführen, d.h die veränderten Daten in einen Zwischenspeicher abzulegen.<code>git stash</code> Danach ist es nötig mit dem bereits erwähnten Befehl <code>git pull</code> ein Update zu holen und abschließend den Stash zu bereinigen. <code>git stash list</code> <code>git stash drop stash@{0}</code> Hinweise gibt es im [[https://git-scm.herokuapp.com/book/en/v2/Git-Tools-Stashing-and-Cleaning|GIT-Buch]].
+Ein Update wird dann mit dem Hinweis abbrechen, dass lokale Änderungen durch das Update überschrieben würden und man diese entweder committen (was von FlexNow-Seite aus nicht erwünscht bzw möglich ist) oder diese "Stashen" soll. In diesem Fall bitte ein Stash durchzuführen, d.h die veränderten Daten in einen Zwischenspeicher abzulegen.<code>git stash</code> Danach ist es nötig mit dem bereits erwähnten Befehl <code>git pull</code> ein Update zu holen und abschließend den Stash zu bereinigen. <code>git stash list</code> <code>git stash drop stash@{0}</code> Hinweise gibt es im [[https://git-scm.herokuapp.com/book/en/v2/Git-Tools-Stashing-and-Cleaning|GIT-Buch]].
+Alternativ kann, vor allem bei schwereren Beschädigungen am Repository, mit dem reset-Befehl gearbeitet werden:
+  git reset --hard <commit>
+bringt sowohl den HEAD als auch den Working-Tree (also die verwalteten Dateien) auf den Stand von <commit>.
 ==== Probleme mit Sonderzeichen im Passwort ====
 Falls ein Sonderzeichen im Passwort ist und der Zugang zum GIT-Server verweigert wird, muss das Passwort im lokalen Kunden-Repository in der Datei .../.git/config in Hochkommata gesetzt werden ([[https://stackoverflow.com/questions/32976119/git-ftp-config-settings-with-password-ending-in|Quelle]])
@@ Zeile 134: / Zeile 161: @@
 {{ :fn2:git_pull_error.png?nolink |}}
-==== Link zum GitLab-Server ====
-Der FTP-Server ist für Git nicht mehr verfügbar.
-Deshalb muss in der Datei ''/.git/config'' der Bereich ''remote = "origin"'' folgende URL enthalten:
-<code>[remote "origin"]
-	url = https://gitlab.ihb-eg.de/fn2/fn2webapps.git</code>