Beitragen

Dieses Dokument beschreibt die Entwicklungsrichtlinien und den Prozess fuer Beitraege zum calServer-Projekt.

Entwicklungsumgebung einrichten

Voraussetzungen

• Docker und Docker Compose
• Git
• PHP 7.4 (fuer lokale Analyse und IDE-Unterstuetzung)
• Java 21 (nur bei Aenderungen am Report-Runner)

Lokales Setup

1. Repository klonen:

   git clone git@bitbucket.org:calserver/calwebapp_yii1.git
   cd calwebapp_yii1
   

2. Umgebungsvariablen konfigurieren:

   cp docker/.env.example docker/.env
   # Werte in docker/.env anpassen
   

3. Container starten:

   cd docker
   docker-compose up -d
   

4. Datenbank initialisieren:

   docker exec -it calserver ./httpdocs/protected/yiic migrate
   

Die Anwendung ist danach unter der konfigurierten Domain erreichbar.

Git-Workflow

Branch-Strategie

Das Projekt verwendet einen Git-Flow-aehnlichen Workflow:

Branch	Zweck
master	Produktiver Stand, nur ueber Releases aktualisiert
develop	Integrationsbranch fuer die naechste Version
feature/<name>	Neue Funktionen
bugfix/<name>	Fehlerbehebungen
hotfix/<name>	Dringende Korrekturen am Produktivstand
release/<version>	Vorbereitung eines Releases

Namenskonventionen

• Branch-Namen in Kleinbuchstaben mit Bindestrichen: feature/dcc-xml-export
• Issue-Referenz im Branch-Namen, wenn vorhanden: bugfix/1234-fix-grid-sorting

Commit-Nachrichten

Commit-Nachrichten folgen diesem Format:

<Typ>: <Kurzbeschreibung>

<Optionale ausfuehrliche Beschreibung>

Refs #<Issue-Nummer>

Typen:

Typ	Verwendung
feat	Neue Funktion
fix	Fehlerbehebung
refactor	Code-Umstrukturierung ohne Funktionsaenderung
docs	Dokumentationsaenderungen
test	Tests hinzufuegen oder aendern
chore	Build-Skripte, Abhaengigkeiten, Konfiguration

Code-Standards

PHP

• Einrueckung: Tabs
• Klammern: Oeffnende Klammer auf derselben Zeile
• Namensgebung: CamelCase fuer Klassen, camelCase fuer Methoden und Variablen
• Yii-Konventionen: Controller-Aktionen als actionMethodName, Models mit Tabellenname
• Keine unnoetigen use-Statements -- Yii 1.1 verwendet import in der Konfiguration

Datenbankmigrationen

Schemaaenderungen werden ausschliesslich ueber Yii-Migrationen vorgenommen:

./yiic migrate create <beschreibung>

Jede Migration muss eine up()- und eine down()-Methode implementieren.

Frontend

• JavaScript: jQuery (vom Yii-Framework bereitgestellt)
• CSS: Bootstrap 3 (ueber die Booster-Extension)
• Templates: Yii-PHP-Views unter views/

Pull-Request-Prozess

1. Erstellen Sie einen Feature- oder Bugfix-Branch ausgehend von develop
2. Implementieren Sie die Aenderungen mit aussagekraeftigen Commits
3. Stellen Sie sicher, dass vorhandene Tests weiterhin bestehen
4. Erstellen Sie einen Pull Request gegen develop
5. Beschreiben Sie im PR die Aenderung, den Grund und die Testabdeckung
6. Warten Sie auf das Code-Review durch mindestens einen Reviewer
7. Nach Genehmigung wird der Branch in develop gemergt

Review-Kriterien

• Code entspricht den beschriebenen Standards
• Datenbankmigrationen sind vorhanden und reversibel
• Keine hartcodierten Konfigurationswerte
• Mandantentrennung bleibt gewahrt
• Berechtigungspruefungen sind vorhanden

Testing

Testtypen

Typ	Werkzeug	Verzeichnis
Unit-Tests	PHPUnit	httpdocs/protected/tests/
Akzeptanztests	Behat	httpdocs/protected/features/
API-Tests	Behat	httpdocs/protected/features/api/
Report-Runner-Tests	JUnit	report-runner/src/test/

Tests ausfuehren

# PHPUnit
docker exec -it calserver ./httpdocs/protected/vendor/bin/phpunit

# Behat
docker exec -it calserver ./httpdocs/protected/vendor/bin/behat

Dokumentation

Die Dokumentation wird mit MkDocs Material erstellt und liegt unter docs/. Lokale Vorschau:

pip install -r requirements-docs.txt
mkdocs serve

Beim Hinzufuegen neuer Seiten muss der Eintrag in mkdocs.yml unter nav: ergaenzt werden.