Dieser Artikel soll Dir dabei helfen deinen Rechner so einzurichten, dass Du beim Eingeben von Splittermond-Daten mithelfen kannst.

Grundsätzlich braucht man dafür einen XML-Editor und einen Git-Client. Beides wird in der Regel von integrierten Entwicklungsumgebungen (IDE) wie Intell-J oder Eclipse unterstützt. Da ich eigentlich nur Erfahrungen mit Eclipse habe, ist diese Anleitung speziell auf diese IDE zugeschnitten. Die grundsätzlichen Schritte gelten aber auch für andere IDEs.

Einrichtung

Die folgenden Schritte sind lediglich einmalig nötig.

1. Einrichten eines Bitbucket-Kontos

Unsere Daten werden in einem sogenannten Git-Repository aufbewahrt. Dieses wird gehostet von dem Anbieter Atlassian auf der Plattform Bitbucket.

Gehe zu http://bitbucket.org/ und lege Dir dort einen Account an.

2. Warten das Du in das Team aufgenommen wirst

Aufgrund von Auflagen durch den Uhrwerk Verlag dürfen wir das Repository nicht für die Allgemeinheit lesbar machen. Du musst daher von uns explizit ins Team aufgenommen werden.

Mail deinen Bitbucket-Account an uns (genesis @ rpgframework.de) und warte auf Bestätigung.

3. Installier Dir Java 11 und Eclipse

Java: https://jdk.java.net/11/ (Die Dateneingabe geht auch via OpenJDK, Fürs Frontent also Genesis benötigt man ein Oracle JDK)
Eclipse: https://www.eclipse.org/downloads/packages/ und wähle "Eclipse IDE for Java Developers"

4. Teile Eclipse mit, dass es Java 11 verwenden soll

Je nachdem was auf deinem Rechner vorher los war, kann es sein, dass Du in Eclipse noch einrichten musst, dass Java 11 verwendet wird. Gehe dazu unter "Window → Preferences" und in dem aufkommenden Dialog unter "Java → Installed JREs"

Falls dort dein Java nicht aufgeführt ist, füge es über den "Add"-Button hinzu.

5. Einen View in Eclipse für Git öffnen

Gehe auf Window → Show View → Other und in dem folgenden Dialog zu Git → Repository Browser

6. Eine Kopie der Daten aus dem Repository laden

Dieser Schritt sorgt dafür, dass eine lokale Kopie der Splittermond-Daten auf deinen Rechner geladen wird. Dazu brauchst Du die URL des Repositorys. Dazu gibt es zwei Wege:

Individuell: Du gehst auf die Webseite https://bitbucket.org/rpgframework/splittermond-data/src/master/ und wählst den "Clone"-Button oben rechts. Aus dem aufpoppenden Fenster kopiere alles ab (und einschließlich ) "http".
Allgemein: Du kopierst Dir einfach diese allgemeine URL: https://bitbucket.org/rpgframework/splittermond-data.git

Jetzt wechselst Du wieder auf Eclipse und in den Repository Browser.

In dem Repository Browser wähle "Clone a Git repository". Daraufhin erscheint ein Dialog, in dem sehr wahrscheinlich die URL schon vorausgefüllt ist. Stelle sicher, dass Login und Passwort deines Bitbucket-Accounts eingegeben werden.

Auf der Dialog-Seite "Local Destination" kannst Du bestimmen, wohin auf deine Festplatte die Daten kopiert werden sollen. Zudem solltest Du das Häkchen bei "Import all existing ..." setzen.

Nach Beendigung des Dialogs beginnt Eclipse mit dem Download er Daten. Im Anschluß solltest Du in deiner Projektliste links das Projekt "Splittermond_Data" sehen.

Gratuliere. Du hast alle nötigen Tools installiert, um dich in die Arbeit stürzen zu können.

Mitarbeiten

Du hast jetzt zwar die Splittermond-Daten auf deinen Rechner geklont, aber Du kannst keine Änderungen zurückschreiben. Dazu musst Du erst soetwas wie deinen Arbeitsbereich auf dem Server einrichten. Hier gibt es zwei Möglichkeiten:

Du forkst das Projekt
Ein Fork erzeugt eine Kopie des Projekts in deinem privaten Bitbucket-Account. In speziellen Falle von Splittermond kannst nur Du die Kopie sehen und darauf zugreifen. Dein Fork ist natürlich für dich schreibbar.
Ein Fork ist sinnvoll, wenn Du alleine vor dich hinarbeiten wirst und Dich mit niemanden abstimmen musst.
Du erzeugst einen Branch
Ein Branch erzeugt ebenfalls eine Kopie des Projekts, allerdings im Team-Bereich des Projekts. Jedes Teammitglied kann die Kopie lesen und schreiben.
Ein Branch ist sinnvoll, wenn Du mit anderen Teammitgliedern an einer Aufgabe arbeiten wirst.

A) Das Projekt forken

Um den Fork zu erzeugen, log dich wieder bei Bitbucket (https://bitbucket.org/rpgframework/splittermond-data/src/master/) ein. Am linken Rand gibt es ein "+"-Button, der ein Menü öffnet, wo Du die Option zum Forken bekommst.
Wenn Du es genauer wissen willst, kannst Du auch folgende Anleitung lesen: https://confluence.atlassian.com/bitbucket/forking-a-repository-221449527.html

Du landest nach dem Fork wieder auf einer Webseite, die der davor sehr ähnlich sieht, aber die URL ist eine andere.

Das ist jetzt ein neues Git-Repository, d.h. Du musst es wieder klonen. Die URL zum Klonen bekommst Du, in dem Du oben rechts den "Clone"-Button betätigst. Mit dieser URL wiederholst Du den Schritt 6 aus der Ersteinrichtung (s.o.).
Bevor Du das aber machst, solltest Du das bisherige Projekt "Splittermond_Data" in Eclipse löschen (nur das Projekt, nicht die Dateien auf der Platte), da es sonst zum Konflikt kommt.

B) Das Projekt branchen

Die erste Person der zusammenarbeitenden Teammitglieder erzeugt den Branch, indem sie sich bei Bitbucket (https://bitbucket.org/rpgframework/splittermond-data/branches/) einloggt. Oben rechts in der Ecke gibt es den Button "Create branch".

Üblicherweise erzeugt man den neuen Branch ausgehend vom Branch "master". Der Typ hängt davon ab was man vorhat - für DatenNEUeingabe passt "Feature", für Fehlerkorrekturen "Bugfix".

Wenn man Branch erzeugt hat, sollte man in Eclipse im Repository Browser das Repository anklicken und im Kontextmenü "Pull" auswählen. Anschließend wählt man aus dem Kontextmenü "Switch To → Other" und sucht dann unter "Remote Tracking" den eben erzeugten Branch (bzw. den, den die erste Person erzeugt hat)

Die beiden anschließenden Dialoge kann man mit den vorausgewählten Buttons (z.B. "Checkout als new local branch") übernehmen.

Alles da - und nun?

Du findest alle Daten für Splittermond als XML und Properties-Dateien unter src/main/resources/org/prelle/rpgframework/splittermond/data.

Dort gibt es für jedes Regional- oder Regelmodul ein eigenes Unterverzeichnis. Innerhalb dieses Unterverzeichnis sind zwei weitere Verzeichnisse:

data - hier liegen die XML-Dateien
i18n - hier liegen die menschenlesbaren Bezeichnungen (d.h. Namen von Sachen, Seitenverweise, Volltexte)

Für ein neues Projekt wie z.B. ein neuer Regionalband, muss also ein neues Verzeichnis angelegt werden, welches ebenso diese Verzeichnisse enthält. Der Name sollte kurz und ohne Leerzeichen sein. Am besten schaut ihr euch bei anderen Projektverzeichnissen ab, wie das dort aussieht.

Damit die neuen von euch angelegten Daten auch eingeladen werden, muss ein wenig Java programmiert werden. In dem Verzeichnis src/main/java (und tiefer) liegt die Klasse SplittermondDataPlugin.

In dieser Klasse stehen Anweisungen, welche Dateien in welcher Reihenfolge geladen werden. Hier mal ein Beispiel:

logger.info("START -------------------------------Surmakar------------------------------------------");
PluginSkeleton SURM = new PluginSkeleton("Surmakar", "Die Surmakar");
SplitterMondCore.loadEquipment(SURM, ClassLoader.getSystemResourceAsStream(pack+"/surmakar/data/equipment-surmakar.xml"), SURM.getResources(), SURM.getHelpResources());
SplitterMondCore.loadEquipment(SURM, ClassLoader.getSystemResourceAsStream(pack+"/surmakar/data/alchemy-surmakar.xml"), SURM.getResources(), SURM.getHelpResources());
SplitterMondCore.loadEducations(SURM, ClassLoader.getSystemResourceAsStream(pack+"/surmakar/data/educations-surmakar.xml"), SURM.getResources(), SURM.getHelpResources());
SplitterMondCore.loadMaterials(SURM, ClassLoader.getSystemResourceAsStream(pack+"/surmakar/data/materials-surmakar.xml"), SURM.getResources(), SURM.getHelpResources());

Erklärung:

Der erste Parameter beim PluginSkeleton hat zwei Auswirkungen:
1. Er bestimmt (kleingeschrieben) den Namen der Properties-Dateien - in diesem Fall "surmakar.properties" und "surmakar-help.properties"
2. In der Datei X.properties (z.B. "surmakar.properties") wird ein Key "plugin.Surmakar.productname.short" bzw. "..full" erwartet
Jede einzelne Datei wird über entsprechende Load-Methoden aus Splittermond-Core eingeladen. Eclipse bietet hier Autovervollständigung an, wenn ihr die Namen nicht kennt.
Achtet auf die Reihenfolge. Wenn z.B. eine Ausbildung aus der "educations-X.xml" Datei eine Meisterschaft referenziert, muss vorher die Datei mit den Meisterschaften eingeladen worden sein.
Es ist daher auch sinnvoll, dass neue Module immer ans Ende der Java-Methode kommen
Abgesehen davon sind die Dateinamen der XML-Files egal - aber es wäre gut, wenn ihr euch an die bisherige Konvention haltet.

Prüfen

Ihr habt Daten eingegeben. Es ist wahrscheinlich, dass einem dabei ein Fehler unterlaufen ist. Um zu prüfen, ob Genesis später in der Lage sein wird, die Daten einzulesen, könnt ihr genau das ausprobieren (ohne Genesis zu starten).

Auch hier gibt es zwei Möglichkeiten:

Direkt in Eclipse
Geht dazu im Verzeichnis src/test/java (und tiefer) auf die Klasse LoadDataTest. Im Kontextmenü findet sich die Option "Run As → JUnit Test". Es wird die Ansicht gewechselt und in der Console von Eclipse laufen Ausgaben durch.

Ein grüner Balken im linken Fenster zeigt an, dass alles eingeladen werden konnte. Achtet aber auch auf die Console, ob dort Fehlermeldungen stehen - z.B. führen Fehler in den Properties-Dateien nicht zum Abbruch, sondern werden nur in der Konsole ausgegeben.
Über Maven
Wählt die Datei "pom.xml" aus. Im Kontextmenu dann "Run As → Maven test". Dadurch wird Maven gestartet, lädt ggf. Abhängigkeiten nach und führt dann den oben genannten LoadDataTest durch.
Wenn ihr Schwierigkeiten mit Option 1 habt, solltet ihr diese hier ausprobieren.

Arbeit sichern

Irgendwann kommt ihr an den Punkt, an dem ihr Feierabend macht. Jetzt heisst es, die Arbeit wegsichern. Dazu geht ihr im Repository Browser ("Git Repositories") auf das Repositiory und wählt im Kontextmenü "Commit". Ein Fenster erscheint am unteren Rand (oder als Dialog, je nachdem wie Eclipse konfiguriert ist), in dem ihr angezeigt bekommt, welche Dateien sich geändert haben und in dem ihr eine kurze Nachricht einfügen müsst. Man fasst hier üblicherweise knapp zusammen, was man getan hat.

Ihr müsst euch dann noch zwischen "Commit" und "Commit and Push" entscheiden:

Commit - Erzeugt quasi eine Art Savegame eurer Arbeit auf eurem Computer. Niemand sonst kann die Änderung sehen.
Wollt ihr zu einem späteren Zeitpunkt die Arbeit auf den Server (d.h. Bitbucket) schreiben, müsst ihr im Kontextmenü des Repositories "Push" auswählen.
Commit and push - speichert eine lokale Sicherung eurer Arbeit UND lädt diese zu Bitbucket hoch. Solltet ihr in einem Branch mit anderen arbeiten, können diese eure Fortschritte anschauen.

Fertig - was jetzt?

Du (oder der verantwortliche Editor deiner Gruppe) bist der Meinung, dass alles getan ist? Die Tests liefen problemlos durch. Alle Tasks sind abgearbeitet? Dann heisst es jetzt, den Maintainern Bescheid zu geben, dass die Änderungen übernommen werden können. Bei Git nennt man das "Pull Request" (Du forderst den Inhaber des Ursprungsrepositories/master-Branches dazu auf, deine Änderungen zu übernehmen).

Geh dazu im Browser zu Bitbucket - entweder zu dem Branch (s.o.) oder zu deinem Fork. Wähle am linken Rand das "+"-Symbol und dann "Create a pull request". Au der folgenden Seite kannst Du noch eine Anmerkung zu der ergfolgten Arbeit schreiben - quasi eine Nachricht an die Maintainer.

Diese werden benachrichtigt und können alle deine Änderungen sehen. Unter Umständen gibt es Rückfragen oder Verbesserungswünsche.

Browser not supported