Skip to content

Commit

Permalink
cleanup README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@Glutamat42
Glutamat42 committed Sep 3, 2024
1 parent 75f877c commit cce0253
Showing 1 changed file with 31 additions and 83 deletions.
114 changes: 31 additions & 83 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,14 @@


## Dependencies
> [!CAUTION]
> Now removed all dependency checks for all plugins as I'm pissed of about moodle saying: no you cannot update, because
> the updated version of the dependency that IS ALREADY PRESENT IN THE CORRESPONDING DIRECTORY is "Unavailable".
> [!NOTE]
> Dieses Projekt folgt nicht vollständig dem Moodle-Ansatz zur Angabe von Abhängigkeiten in der version.php-Datei,
> da dies Probleme bei Updates und Deinstallationen verursacht.
| Plugin | Version |
|--------------------|---------|
| availability_adler | ~3.0.0 |



## MBZ api endpunkt
Damit der mbz api endpunkt auch mit größeren Dateien funktioniert sind folgende Änderungen an der php.ini notwendig:
```
- `post_max_size` auf mindestens 2048M setzen
- `upload_max_filesize` auf 2048M setzen
- `max_input_time` auf 600 setzen
- `memory_limit` auf mindestens 256M setzen
- `max_execution_time` auf mindestens 60 setzen
- `output_buffering` auf 8192 setzen
```
todo: some variable might not be required anymore after upload_course rework
| local_logging | jede |


## Kompabilität
Expand All @@ -42,42 +29,27 @@ Folgende Versionen werden unterstützt (mit mariadb und postresql getestet):
| MOODLE_404_STABLE | 8.3 |


## Deinstallation der Plugins
### Halbautomatische Deinstallation
Es gibt ein dev_utils script, welches dieses Plugin deinstalliert `php local/adler/dev_utils/uninstall_plugin.php`.
Möglicherweise wird dieses Script in Zukunft zu einem PHP CLI script ausgebaut.

### Manuelle Deinstallation und Erklärung des Problems
Die Plugins sind gegenseitig voneinander abhängig. Diese sind ausschließlich dafür gedacht in Kombination verwendet zu werden,
für sich alleine können diese nicht eingesetzt werden. Der Uninstaller von moodle kann Plugins mit gegenseitigen Abhängigkeiten
nicht deinstallieren. Dazu gibt es eine "Won't fix" Issue im moodle issue tracker: [MDL-55624](https://tracker.moodle.org/browse/MDL-56624).
Die Deinstallation der Plugins erfordert deshalb manuelles Eingreifen.
1. In der Datei `local/adler/version.php` das Feld `$plugin->dependencies` komplett löschen.
2. Evtl. ist ein Erhöhen der Versionsnummer und ein upgrade der Moodle Installation notwendig.
3. Die Plugins können nun deinstalliert werden.

Ein alternativer Ansatz dazu könnte wie folgt aussehen: Das Plugin `availability_adler` kann im Grunde eigenständig installiert werden,
ist dann aber ohne Funktion, da es ohne das Plugin `local_adler` nicht funktionieren kann (alle Adler-Conditions werden deshalb als
erfüllt behandelt). Die Abhängigkeit des Plugins `availability_adler` von `local_adler` könnte somit entfernt werden. So könnten
die Plugins erwartungsgemäß deinstalliert werden. Dieser Ansatz hätte aber die folgenden gravierenden Nachteile:
- Dem Moodle Plugin Konzept folgend dürfte `availability_adler` nicht auf Funktionen von `local_adler` zugreifen, da keine Abhängigkeit
besteht. Dies würde aber bedeuten, dass die Adler Raumlogiken nicht funktionieren können.
- Wird `local_adler` deinstalliert verbleibt `availability_adler` installiert und muss danach manuell entfernt werden.
- Wird `availability_adler` installiert wird `local_adler` nicht automatisch installiert.
## MBZ api endpunkt
Damit der mbz api endpunkt auch mit größeren Dateien funktioniert sind folgende Änderungen an der php.ini notwendig:
```
- `post_max_size` auf mindestens 2048M setzen
- `upload_max_filesize` auf 2048M setzen
- `max_input_time` auf 600 setzen
- `memory_limit` auf mindestens 256M setzen
- `max_execution_time` auf mindestens 60 setzen
- `output_buffering` auf 8192 setzen
```
todo: some variable might not be required anymore after upload_course rework


## Setup

Setup funktioniert exakt wie bei allen anderen Plugins auch (nach dem manuellen Installationsvorgang, da unser Plugin nicht im Moodle Store ist).

1. Dieses Plugin benötigt das Plugin `availability_adler` als Abhängigkeit. Beide müssen zeitgleich installiert werden (= vor dem upgrade in die Moodle-Installation entpackt sein). Installation siehe `availability_adler`
2. Plugin in moodle in den Ordner `local` entpacken (bspw moodle/local/adler/lib.php muss es geben)
1. Dependencies beachten
2. Plugin in moodle in den Ordner `local` entpacken (bspw. moodle/local/adler/lib.php muss es geben)
3. Moodle upgrade ausführen

Damit ist die Installation abgeschlossen. Als Nächstes kann ein mbz mit den Plugin-Feldern wiederhergestellt werden.


### Kurs mit dummy Daten seeden
### Kurs mit Testdaten seeden
Für Testzwecke können bestehende normale Kurse mit dummy Daten gefüllt werden.
Im Ordner `dev_utils` liegt dazu das Skript `seed.php`.

Expand All @@ -94,53 +66,29 @@ Nun kann dieser Kurs zum Testen genutzt werden.
## Dev Setup / Tests
Dieses Plugin nutzt Mockery für Tests.
Die composer.json von Moodle enthält Mockery nicht, daher enthält das Plugin eine eigene composer.json.
Diese ist (derzeit) nur für die Entwicklung relevant, sie enthält keine Dependencies die für die normale Nutzung notwendig sind.
Um die dev-dependencies zu installieren muss `composer install` im Plugin-Ordner ausgeführt werden.

### Unit Test Setup
- Den richtigen Interpreter wählen (im Falle von der Nutzung von WSL muss bspw unbedingt der Interpreter innerhalb der WSL Installation gewählt werden)
- moodle composer.json installieren (`cd <path-to-moodle>; composer install`)
- plugin composer.json installieren (für jedes Plugin dessen tests ausgeführt werden sollen) (`cd <path-to-plugin>; composer install`)
- Moodle hat eine hardcoded locale dependency bei Tests für `en_AU.UTF-8` ([siehe docs](https://docs.moodle.org/dev/Common_unit_test_problems#core_phpunit_advanced_testcase::test_locale_reset)). Diese muss generiert werden: Ubuntu: `sudo locale-gen en_AU.UTF-8`
- phpunit.xml aus dem Projekt auswählen (geschieht über den `--configuration` switch von phpunit)
Für das weitere Test-Setup siehe [AdlerDevelopmentEnvironment](https://github.com/ProjektAdLer/AdlerDevelopmentEnvironment/tree/main/moodle),
dort sind auch die Schritte zur weiteren PHPStorm Konfiguration beschrieben.

Hinweise:
- Um Tests lokal nicht in `@RunTestsInSeparateProcesses` ausführen zu müssen in der Datei `moodle/lib/setuplib.php` in der Funktion `require_phpunit_isolation()` vor der Exception `return;` einfügen. \
**Achtung**: Dies kann potentiell unerwartete Nebeneffekte haben! Tests werden nicht umsonst normalerweise in isolierten Prozessen ausgeführt.


## Verschiedenes

### Context ID für xapi events
- Um Tests lokal nicht in `@RunTestsInSeparateProcesses` ausführen zu müssen in der Datei `moodle/lib/setuplib.php` in
der Funktion `require_phpunit_isolation()` vor der Exception `return;` einfügen. \

xapi Events nutzen die Context-ID, um die Kurs-ID zu referenzieren.
Diese sind aktuell über keine API des Plugins verfügbar, da sie für das moodle-interne Rechtemanagement gedacht sind.
Um für Testzwecke die context-id eines Lernelements zu erhalten, kann wie folgt vorgegangen werden:
- **Achtung**: Dies kann potenziell unerwartete Nebeneffekte haben! Tests werden nicht umsonst normalerweise in
isolierten Prozessen ausgeführt.

1. cmid des Lernelements herausfinden: h5p Element im Browser öffnen, in der URL steht die cmid als Parameter `id=123` (bspw `http://localhost/mod/h5pactivity/view.php?id=2`)
2. in der DB folgende query ausführen: `SELECT id FROM mdl_context where contextlevel = 70 and instanceid = 2;` (`instanceid` ist die id aus step 1)


### Löschen eines Kurses / von Lernelementen

Beim Löschen eines Kurses oder Lernelements werden die Daten aus der Datenbank gelöscht. Dabei gibt es aber zwei Dinge zu beachten:

1. Moodle hat einen Trashbin der standardmäßig aktiv ist. Dann werden die Daten erst Zeitverzögert gelöscht. Ob dies wirklich funktioniert wurde bisher nicht getestet, sollte aber
funktionieren.
2. Wird ein Kurs gelöscht gibt es keine mir bekannte Möglichkeit zu erfahren, welche Kursbestandteile dabei entfernt wurden.
Daher wird nach Löschen eines Kurses für alle Adler-Score Einträge verglichen, ob das dazugehörige cm noch existiert. Dies könnte bei sehr großen Moodle Instanzen zu Performance
Problemen führen.
Die folgende Tabelle zeigt einige Testergebnisse für eine verschiedene Anzahl von Lernelementen in einer Moodle Installation.
Ausgeführt wurde der Test auf einem Github Actions Runner.
## Löschen eines Kurses / von Lernelementen
- Moodle hat einen Trashbin, das tatsächliche Löschen findet zeitverzögert statt.
- Wird ein Kurs gelöscht gibt es keine Möglichkeit zu wissen, welche Lernelemente dabei entfernt wurden.
Nach dem Löschen eines Kurses wird für alle Adler Einträge verglichen, ob das dazugehörige cm noch existiert.
Dies könnte bei sehr großen Moodle Instanzen zu Performance Problemen führen.
Ein workaround wäre eine redundante Datenhaltung der Kurs-ID bei jedem Eintrag.

| Anzahl verbleibende Lernelemente mit Adler-Scores | Anzahl der Lernelemente mit Adler-Scores des gelöschten Kurses | Zeit |
|---------------------------------------------------|----------------------------------------------------------------|-------|
| 100 | 10 | 0,01s |
| 100 | 100 | 0,07s |
| 1k | 10 | 0,05s |
| 1k | 100 | 0,12s |
| 10k | 10 | 2,4s |
| 10k | 100 | 2,5s |
| 100k | 100 | 186s |

Ein alternativer Ansatz wäre eine redundante Datenhaltung der Kurs-ID. Dies würde die Performanceprobleme umgehen.

0 comments on commit cce0253

Please sign in to comment.