Tutorial: Dein erstes modified eCommerce Shop Modul veröffentlichen

Bearbeitungszeit: ca. 25 min.

In diesem Tutorial lernst du, wie du dein modified eCommerce Shop Modul für den MMLC veröffentlichst. Durch eine Veröffentlichung steht allen MMLC-Nutzern dein Modul zum Download über den MMLC zur Verfügung.

Wichtig: Bevor du ein Modul im MMLC veröffentlichst, empfehlen wir dir dringend, die Guidelines - Checkliste - modified Module veröffentlichen im MMLC zu lesen. In dieser Checkliste findest du wichtige Informationen und Hinweise, auf die du unbedingt achten solltest, bevor du dein Modul veröffentlichst.

Info: Natürlich kannst du festlegen, ob ein Modul nur für bestimmte Nutzer sichtbar ist oder ob dein Modul kostenpflichtig erworben werden muss. Was du hierfür zusätzlich machen musst, erfährst du unter XXX.

Vorbedingungen #

Damit du mit diesem Tutorial starten kannst, benötigst du ein Modul, dass du für den MMLC vorbereitet hast. Wenn du noch kein Modul für den MMLC programmiert hast, zeigt dir folgendes Tutorial, wie du das machen kannst. Tutorial: Dein erstes Modul mit dem MMLC programmieren.

Du musst dich in der Konsole / Eingabeaufforderung durch deine Verzeichnise mit dem Befehl cd navigieren können.

Zudem benötigst du für dieses Tutorial einige einfache Git-Grundlagen. Du solltest Git-Repositors initialisieren können, Commits in dein lokales Git-Repository machen können und dein Repository per push zu einem entfernten Server (wie GitHub, GitLab, etc.) senden können. Aus diesem Grund musst du Git auf deinem System installiert haben. In diesem Tutorial verwenden wir die Konsole, um Git-Befehle einzugeben und zu nutzen. Du kannst natürlich auch einen grafischen Git-Client deiner Wahl verwenden (wie z. B. SourceTree oder GitHub Desktop). In diesem Tutorial nutzen wir jedoch den üblichen Weg über die Konsole.

Wenn du dich mit Git noch nicht auskennst, schaue dir ein paar Einsteiger-Tutorials im Internet an. Hier gibt es eine große Anzahl an guten Tutorials, die dir beim Erlernen von Git helfen. Du benötigst nur die gängigen Einsteiger-Themen, um mit diesem Tutorial zu starten.

Los gehts #

Stelle dir vor, du hast eine Firma mit dem Namen "My Company" und diese Firma möchte ihr neues Modul mit dem Namen "Mein erstes Modul" veröffentlichen. Wenn du noch kein Modul mit dem MMLC entwickelt hast, erfährst du hierzu mehr unter: Tutorial: Dein erstes Modul mit dem MMLC programmieren.

Wichtig: Wenn in diesem Tutorial das Root-Verzeichnis von deinem Modified Shop gemeint ist, schreiben wir SHOP_ROOT. In dem Root-Verzeichnis liegt dein ModifiedModuleLoaderClient. Wenn nichts anderes erwähnt wird, werden alle Pfadangaben in diesem Tutorial relativ zu dem Verzeichnis ModifiedModuleLoaderClient angegeben. Zudem verwenden wir in diesem Tutorial als Beispiel das Modul aus dem Tutorial: Dein erstes Modul mit dem MMLC programmieren mit dem archiveName mycompany/my-first-module.

Wähle deine Plattform #

Damit du ein Modul im MMLC veröffentlichen kannst, musst du dein Modul zunächst per Git hosten. Git ist ein sehr praktisches und wichtiges Werkzeug und gehört mittlerweile zur Standardausrüstung fast aller Entwickler. Du kannst eine beliebige Git-Hosting-Plattform verwedenen oder deinen eigenen Git-Server. Wichtig ist, dass du dein Git-Repository so konfigurieren kannst, dass eine externe Software dein Git-Repository clonen darf.

Dieses Tutorial zeigt dir die nötigen Schritte für die beiden gängigsten Git-Hosting-Plattformen GitHub und GitLab. Wenn du nicht genau weißt, welche Plattform du verwenden sollst, empfehlen wir dir mit einem kostenlosen öffentlichen GitHub Repository zu starten. GitHub ist der größte und bekannteste Anbieter und du findest hier viel Hilfe, wenn du mal nicht weiter kommst.

GitHub - Öffentliches Repository #

Wenn du bereits ein Account bei GitHub hast, kannst du diesen Account auch für deine Module verwenden, die du im MMLC veröffentlichen möchtest. Wenn du noch keinen Account bei GitHub hast, ist jetzt der Zeitpunkt, an dem du dir einen GitHub-Account erstellen musst, um mit diesem Tutorial weitermachen zu können. Du kannst diesen GitHub-Account auch jederzeit für Projekte verwenden, die du abseits des MMLCs realisierst. Nachdem du dir einen kostenlosen Account bei GitHub angelegt hast, geht's dann hier im Tutorial weiter.

Neues Repository erstellen

Als nächstes musst du ein öffentliches Git-Repository auf GitHub für dein Modul erstellen. Das Repository kannst du beliebig benennen, es bietet sich jedoch an, den technischen ModulNamen moduleName deines Moduls zu verwenden. Im Tutorial: Dein erstes Modul mit dem MMLC programmieren wurde der moduleName my-first-module verwendet.

Wähle Public als Einstellung für dein Repository aus und lasse alle anderen Optionen unausgewählt. Das erleichert uns die nächsten Schritte. Du kannst die von GitHub vorgeschlagenen Dateien noch später hinzufügen. Wenn du möchtest, kannst du jedoch schon an dieser Stelle eine kurze Beschreibung hinzufügen, was dein Modul kann. Das geht aber auch später und ist erst einmal nicht wichtig. Klicke dann auf Create repository.

GitHub Öffentliches Repository erstellen

Am besten du schaust jetzt einmal lokal auf deinem Rechner nach, ob du in deinem Modul bereits ein Git-Repository initialisiert hast. Dazu navigierst du mit der Konsole in dein Modul-Ordner und gibst da den Befehl git status ein.

> cd ./Modules/mycompany/my-first-module > git status < fatal: not a git repository (or any of the parent directories): .git

Dokumentation in Arbeit ...

Jetzt kannst du mit dem Schritt Versionsnummer vergeben weitermachen.

GitHub - Privates Repository #

Bei privaten GitHub Repositories musst du einen AccessKey erstellen, damit der MMLS Zugriff auf deine Repositories erhält. Einer Anleitung, wie du einen AccessKey auf GitHub erstellst erhällst du unter: https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line.

Bei den Optionen reicht es aus, wenn du lediglich einen Haken bei repo (Full control of private repositories)setzt.

GitHub privates Repository

Jetzt kannst du auf dein Repository zugreifen, indem du vor github.com/... deinen GitHub USER_NAME, gefolgt von einem Doppelpunkt, gefolgt von deinem neuen TOKEN, gefolgt von einem @-Zeichen schreibst.

Hier ein Beispiel: https://USER_NAME:TOKEN@github.com/mycompany/my-first-module.git

GitLab - Öffentliches Repository #

Dokumentation in Arbeit ...

GitLab - Privates Repository

Dokumentation in Arbeit ...

Versionsnummer vergeben #

Es ist wichtig, dass du deinem Modul eine oder mehrere Versionsnummern gibst. Versionen werden über git tags verwaltet. Das Format der Versionsnummer muss der Semantic Versioning (SemVer) Spezifikation entsprechen. Informationen zu SemVer findest du unter semver.org.

In der moduleinfo.json deines Moduls solltest du im Feld version den Wert auto eintragen. Diese Einstellung sorgt dafür, dass der MMLS sich an den Releases / Veröffentlichungen deines Git-Repositorys orientiert.

Einen neuen Release / eine Veröffentlichung machst du, indem du einen Commit mit einer Versionsnummer taggst. Wenn du z. B. dein Modul in der Version 1.0.0 veröffentlichen möchtest, wählst du einen passenden Commit aus und taggst diesen mit 1.0.0.

Hier findest du ein Beispiel wie es beim Modul robinthehood/modified-std-module gemacht wurde.

Wichtig: Wenn du in deinem Git-Repository keine Versionsnummern vergibst, wird der MMLS keine Versionen finden, die er an den MMLC ausspielen kann.

MMLS Accout erstellen #

Account erstellen auf app.module-loader.de

Damit deine Module für alle MMLC Nutzer verfügbar werden, musst du dem MMLC mitteilen, wo der MMLC diese Module findet. Hierzu befragt der MMLC den Modified Module Loader Server (MMLS). Der MMLS ist die zentrale Vermittlungsstelle, welche die Module an alle MMLCs verteilt.

Wir erstellen hierzu einen Account bei app.module-loader.de. Du musst beim Erstellen deines Accounts einen vendorName wählen. Dieser vendorName muss der Gleiche sein, den du für deine Module verwendest. Im Root-Verzeichnis deiner Module befindet sich jeweils die moduleinfo.json Datei, die du erstellt hast. Hier gibt es einen Eintrag archiveName. Dieser Name ist zusammengesetzt aus vendorName / moduleName.

Wichtig: Du (oder dein Unternehmen) musst den vendorNamen deiner Module verwenden. Weitere Informationen findest du unter Naming Convention.

MMLS Account erstellen

MMLS Eintrag erstellen #

Nachdem du dir einen Account im MMLS erstellt hast, kannst du dein Modul-Archive zum MMLS hinzufügen. Hierfür musst du die Werte für type, moduleName und source richtig ausfüllen, damit der MMLS und der MMLC dein Modul finden.

type

Hier kannst du git, github oder gitlab auswählen. Wähle hier die Plattform aus auf der sich dein Git-Repository befindet. Wenn deine Plattform nicht dabei ist oder du einen eigenen Git-Server betreibst wähle hier git aus.

moduelName

Hier musst du den technischen moduleName eintragen, den du in deiner moduleinfo.json vergeben hast. In der moduleinfo.json findest du den archiveName. Dieser setzt sich zusammen aus deinem vendorName und dem vom MMLS benötigten moduleName. Mehr dazu finest du unter Die moduleinfo.json.

source

Hier gibst du die Url zu deinem Git-Repository ein. Bei privaten nicht öffentlichen Repositories musst du zusätzlich zur Url oft einen Username und Token mit angeben. Wie das bei einem privaten Git-Repositiory auf GitHub funktioniert ist weiter oben in diesem Tutorial beschrieben.

Wenn du ein öffentliches Repository auf GitHub erstellt hast, kannst du die https-url zu deinem Repository direkt von GitHub kopieren. In unserem Beispiel wäre das die Url https://github.com/RobinTheHood/my-first-module.git. Das folgende Bild zeigt dir, wo auf GitHub du die Url findest. Wähle hier HTTPS aus.

MMLS Account erstellen

Nun haben wir alle Daten für unseren neuen Eintrag zusammen. In unserem Beispiel mit dem öffentlichen GitHub-Repository, müssen wir die Eingabe wie im folgendem Screenshot dargestellt ausfüllen.

MMLS mit Daten für ein GitHub Repository

MMLS Eintrag aktualisieren #

Nachdem wir usneren Eintrag vollstänig ausgefüllt haben können wir uns alle nötigen Releases aus unserem Git-Repository holen.

MMLS Eintrag vor dem ersten Update

Dazu klicken wir auf Update. Nun synchronisiert der MMLS den Eintrag mit allen Tags/Versionen aus dem Git-Repository. Im folgendem Beispiel kannst du sehen, dass der MMLS jetzt die Version 0.1.0 erfolgreich kennt.

MMLS Eintrag nach dem ersten Update