# Odysseereader-Data

Hier sind die DATEN für das OdysseeReader Projekt.

## Abhängigkeiten des Repositories (Flask-Only)
* `python 3` - muss installiert sein
* `flask` (pip install Flask)

## Verzeichnisse des Repositories
* `cisptt` - beinhaltet die Daten von Herrn Dr. Dr. Pilch sowie die aufbereiteten Daten die für den Odyssee-Reader vor der Laufzeit erzeugt werden
* `faksimile` - hier werden die Bilddateien des Manuskripts Ms-104 für die lokale Verwendung abgelegt
* `Graphics` - neuer Ordner um die SVG-Dateien die Herr Pilch erstellt zu speichern und später zu im Reader zu verwenden
* `IMG` - Bilder und Screenshots etc. die nicht direkt im Reader verwendet werden, aber diesen betreffen (bspw. um etwas zu besprechen)
* `tools` - enthält weitere Unterordner mit Werkzeugen für den E-Reader e.g. für die Daten-aufbereitung

## Neue Daten erzeugen/ändern, Arbeit mit git

**Was ist git:** Hier eine sehr gute Einführung: https://studi.f4.htw-berlin.de/www/help/tutorial/git/

### Installation der git Befehle für Windows

* hier zum Download: https://git-scm.com/download/win
* hier zum Arbeiten unter Windows: https://www.kim.uni-konstanz.de/services/datenserver-und-cloud/versionsverwaltung-git-gitlab/git-client-unter-windows/  
 (hier wird auch beschrieben, wie ein ssh-Key erzeugt wird, damit die Kommunikation mit dem git-server ohne Passwort möglich ist)


### Holen der Daten vom Server 
(aus dem Git-Repository) / Herunterladen der Daten auf den eigenen Rechner in ein lokales Verzeichnis

Um die Daten aus dem Git-Repository vom CIS-Server lokal auf dem eigenen Rechner zur Verfügung zu haben (man nennt dies: clonen der Daten) 
und somit auch ändern zu können, öffnet man die Windows `Git-Bash` und es öffnet sich ein Kommandofenster, in das man 
entsprechende git-Befehle  eingeben kann.

* 1. Speichert die Daten aus dem Git-Projekt Odysseereader-Data (Branch:Master) in dem Verzeichnisss `odysseereader-data` lokal ab
* $  `git clone git@gitlab.cis.uni-muenchen.de:wast/odysseereader-data.git odysseereader-data`

Bemerkung: Wenn das Repository schon auf den lokalen Rechner geholt wurde, dann muss es zuerst gelöscht werden: 
(Fehlermeldung: `fatal: destination path 'odysseereader-data' already exists and is not an empty directory.`)
* $ `rm -rf odysseereader-data`

### Wechseln in das geclonte Repository:
**WICHTIG** Nach dem Herunterladen der Daten aus dem Repository müssen Sie in das Verzeichnis der heruntergeladenen 
Repositories wechseln:
```bash
$ cd odysseereader-data
MINGW64 ~/odysseereader-data (master) 
```

### Information über ihre Daten und den aktuellen Branch des Repositories und die geänderten Daten
Ein ganz wichtiger Befehl ist `git status`. Dieser git Befehl sagt ihnen, im welchem Zweig sie momentan arbeiten und welche Daten 
des Repositories Sie momentan geändert haben. (Am Anfang ist alles `clean`)
```bash
$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean
```
In diesem Zweig (=Branch) haben sie keine Schreibrechte, wenn Sie also was ändern wollen, dann müssen Sie einen neuen Zweig anlegen und
in diesem Branch arbeiten. 

### Anzeigen aller Branches und die letzten Commits

* `$ git branch -a` : um zu sehen welche Branches es gibt, beziehungsweise wie man sie schreibt (Branchname in [ ] - e.g. `[master] Last commit message here!`)
```bash
$ git branch -a 
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master
  remotes/origin/revert-baa91de8
  remotes/origin/test
```
(Ein sehr ausführlicher Befehl der alle Branches und Commits zeigt, ist: `$ git show-branch -a --list`)

### einen neuen Branch anlegen: wechseln in einen neuen Branch
Es ist ganz wichtig, dass man die neuen Änderungen an den EXCEL Dateien in einem neuen Branch durchführt, da sie, wie gesagt, im
master-branch keine Schreibberechtigung haben.

**deshalb: Erzeugen Sie einen neunen Branch und wechseln Sie in den neuen Branch**

* Durch das Kommando `git checkout -b BRANCHNAME` wird dann zum jeweiligen gewünschten Branch gewechselt

e.g. `$ git checkout -b daten_08_02_19`  erzeugt einen neuen Branch `daten_5_feb_19` und wechseln Sie in diesen Branch
```bash
$ git checkout -b daten_08_02_19
Switched to a new branch 'daten_08_02_19'
Max Hadersbeck@zirbel MINGW64 ~/odysseereader-data (daten_08_02_19)

$ git status
On branch daten_08_02_19
nothing to commit, working directory clean
 ```

### Ändern der EXCEL Dateien:

Jetzt geht die Arbeit los... Sie öffnen im Windows-Daten-explorer das Verzeichnis mit den EXCEL-Dateien: 
e.g. für User max: `C:\Users\max\odysseereader-data\cisptt\ptt-to-cis\opensource_nachlass\MS-104_OA\ptt`
und können dort EXCEL-Dateien ändern und neue Dateien abspeichern.


### Abschliessen der Arbeit und Hochladen der lokalen Änderungen und neuen Daten auf den Server und somit in den Odyssee-Reader
 
Damit der Odyssee-Reader merkt, dass Sie etwas geändert haben und ihre neuen Änderungen in der WEB-Oberfläche sichtbar werden,
müssen Sie dem gitlab Repository-Server am CIS ihre geänderten Daten schicken (=sie "pushen" Ihre Daten).

Man nennt diese Arbeit auch "Hochladen der Daten"

Diese Aufgabe erledigen für Sie git Befehle, die in der richtigen Reihenfolge eingegeben werden müssen. 
Wenn ihre geänderten Daten auf dem Repository-Server richtig angekommen sind, startet automatisch auf dem Server
ein Integration-Prozess, die sogenannte: "Continious Integration". Sie übernimmt die 
Verarbeitung/Aufbereitung der Daten und ruft dafür vorgesehenen Tools auf. 

Immer wenn Sie also neue Daten zum git-Server "pushen" startet dieser Integrationsprozess und nach wenigen Minuten sehen Sie 
die Änderungen auf der WEB-Oberfläche (löschen Sie dazu den Cache Ihres Browsers mit der Tasteneingabe Control+F5)

### Die Befehle zum Hochladen der Daten auf den Repository-Server
Um neue/geänderte Daten an den Repository-Server zu schicken und zu integrieren empfiehlt sich folgender Ablauf von Kommandos:
* `$ git status` : zeigt an ob der Branch up-to-date ist oder Änderungen lokal vorhanden sind
```bash
$ git status
On branch daten_08_02_19
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   cisptt/ptt-to-cis/opensource_nachlass/MS-104_OA/ptt/003.xlsx

no changes added to commit (use "git add" and/or "git commit -a")
```

* `$ git add "filename"` : markiert die Datei für den nächsten commit
```bash
$ git add  cisptt/ptt-to-cis/opensource_nachlass/MS-104_OA/ptt/003.xlsx
```

oder Kurzform
```bash
$ git add *
```

* `$ git commit` `-m "YOUR MESSAGE HERE!"` : speichert die Daten für den nächsten commit zusammen mit der Beschreibung (-m "...")
```bash
$ git commit -m "noch ein Test, geändert .xls 'Sonne_xls', Seite 3, Zeile 4"
[daten_08_02_19 967de16] noch ein Test, geändert .xls 'Sonne_xls', Seite 3, Zeile 4
 1 file changed, 0 insertions(+), 0 deletions(-)
```

* `$ git push origin  <BRANCH> ` : lädt die Daten aus dem Zweig <BRANCH> ins Gitlab - in den jeweiligen Branch -. 
```bash
$ git push origin  daten_08_02_19
Counting objects: 8, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (5/5), done.
Writing objects: 100% (8/8), 1.91 KiB | 0 bytes/s, done.
Total 8 (delta 3), reused 0 (delta 0)
remote:
remote: To create a merge request for daten_08_02_19, visit:
remote:   https://gitlab.cis.uni-muenchen.de/wast/odysseereader-data/merge_requests/new?merge_request%5Bsource_branch%5D=daten_08_02_19
remote:
To git@gitlab.cis.uni-muenchen.de:wast/odysseereader-data.git
 * [new branch]      daten_08_02_19 -> daten_08_02_19
```

* Bei Master ist die Änderung danach auf odysseereader.wittfind.cis.lmu.de sichtbar; sonst auf dev.odysseereader.wittfind.cis.lmu.de

Kurz:
* `Befehl> git status` : empfohlen um zu sehen ob Änderungen vorhanden sind
* `Befehl> git commit -am "YOUR MESSAGE HERE!"` :  führt "git add *" vor dem commit automatisch aus
* `Befehl> git push` : Befehl ist danach trotzdem notwendig um die Neuerungen in das Gitlab hochzuladen


### Laden von aktuellen Daten aus Gitlab
```bash
$ Befehl> git status
On branch test
Your branch is up-to-date with 'origin/test'.
nothing to commit, working tree clean
```
Falls hier nicht *up-to-date* erscheint ist der folgende Befehl zwingend notwendig um Probleme und spätere "Merges" zu vermeiden
* `Befehl> git pull` : lädt die Änderungen die noch nicht lokal vorhanden sind auf das Dateisystem des Nutzers - 
* nur die des ausgewählten Branches

### Direktes klonen eines bestimmten (existierenden) Branches

* `git clone git@gitlab.cis.uni-muenchen.de:wast/odysseereader-data.git -b ptt_update odysseereader-data` : -b Branchname erlaubt das direkte klonen
* Mit dem Kommando oben wird direkt der Branch `ptt_update` geklont - es ist nicht mehr notwendig von (master) auf (ptt_update) zu wechseln
* Beispiel Output der Shell
```bash
STILL@TEST MINGW64 /h/Arbeit
$ git clone git@gitlab.cis.uni-muenchen.de:wast/odysseereader-data.git -b ptt_update odysseereader-data
Cloning into 'odysseereader-data'...
remote: Enumerating objects: 298, done.
remote: Counting objects: 100% (298/298), done.
remote: Compressing objects: 100% (139/139), done.
remote: Total 298 (delta 140), reused 288 (delta 133)
Receiving objects: 100% (298/298), 2.90 MiB | 1.76 MiB/s, done.
Resolving deltas: 100% (140/140), done.

STILL@TEST MINGW64 /h/Arbeit
$ cd odysseereader-data

STILL@TEST MINGW64 /h/Arbeit/odysseereader-data (ptt_update)
$ git status
On branch ptt_update
Your branch is up-to-date with 'origin/ptt_update'.
nothing to commit, working tree clean
```

## Shell Example

### Setup - Erstellen einer lokalen Kopie von Odysseereader-data

### Klonen eines Branches
Kommando: `git clone git@gitlab.cis.uni-muenchen.de:wast/odysseereader-data.git -b ptt_update odysseereader-data`

### Wechseln in das Verzeichnis
Kommando: `cd odysseereader-data`

### Aktualisieren der lokalen Dateien
Kommando: `git pull`
Sollte in regelmäßigen Abständen ausgeführt werden um Probleme zu vermeiden - e.g. vor Beginn der Arbeit an den Daten
```bash
git pull
remote: Enumerating objects: 13, done.
remote: Counting objects: 100% (13/13), done.
remote: Compressing objects: 100% (13/13), done.
remote: Total 13 (delta 8), reused 0 (delta 0)
Unpacking objects: 100% (13/13), done.
From gitlab.cis.uni-muenchen.de:wast/odysseereader-data
   e7e9093..820dedc  ptt_update -> origin/ptt_update
   e7e9093..c6176de  master     -> origin/master
Updating e7e9093..820dedc
Fast-forward
 README.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
```

### Prüfen des Verzeichnisses
Kommando: `git status`

* Output mit lokalen Änderungen - Einchecken der Änderungen (falls nicht fehlerhaft; siehe unten) empfehlenswert
```bash
On branch ptt_update
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   cisptt/ptt-to-cis/opensource_nachlass/MS-104_OA/ptt/003.xlsx

no changes added to commit (use "git add" and/or "git commit -a")
```

* Output ohne lokale Änderungen - kein Handeln erforderlich
```bash
On branch ptt_update
Your branch is up-to-date with 'origin/ptt_update'.
nothing to commit, working directory clean
```

### Hochladen/Einchecken von lokalen Änderungen
Kommando 1: `git commit -am "COMMIT-MESSAGE HERE!"`
Dateien/Änderungen werden beim nächsten `push` hochgeladen!
```bash
STILL@TEST MINGW64 /h/Arbeit/odysseereader-data (ptt_update)
$ git commit -am "README.md updated"
[ptt_update 72cdc8a] README.md updated
 1 file changed, 22 insertions(+), 2 deletions(-)
```
Kommando 2: `git push`
Eigentliches hochladen der lokalen Änderungen in das Gitlab!
```bash
STILL@TEST MINGW64 /h/Arbeit/odysseereader-data (ptt_update)
$ git push
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 777 bytes | 0 bytes/s, done.
Total 3 (delta 2), reused 0 (delta 0)
remote:
remote: To create a merge request for ptt_update, visit:
remote:   https://gitlab.cis.uni-muenchen.de/wast/odysseereader-data/merge_requests/new?merge_request%5Bsource_branch%5D=ptt_update
remote:
To gitlab.cis.uni-muenchen.de:wast/odysseereader-data.git
   820dedc..72cdc8a  ptt_update -> ptt_update
```

## Anmelden des Nutzers

git config --global user.email "you@example.com"
git config --global user.name "Your Name"

### Zusätzliche Meldungen  eines Commits
Weitere Fragen, bzw. Bemerkungen zu einer commit-Message können, wenn der Commit im Browserfenster des gitlabs erscheint, am Ende Commit-Message eingeben werden.
Sollte die Bemerkung bei bestimmten Programmieren, bzw. anderen Leuten im gitlab eine "todo" Aufgabe auslösen, dann bitte den Namen des Kollegen, z.B. @max einbauen... 	


### Sehen der Änderungen auf `http://dev.odysseereader.wittfind.cis.lmu.de/`