Dokumentation
Einreichen
Beschreibung
Soll eine entwickelte Bibliothek im Module Store angeboten werden, so muss dies über den Entwicklerbereich auf der Accountseite eingereicht werden.
Entwicklerbereich
Der Entwicklerbereich ist auf der Accountseite unter "Entwicklerbereich" zu erreichen.
Hier werden alle bisherigen Einreichungen aufgelistet. Es werden die Downloads des Moduls sowie der Zustand der einzelnen Kanäle dargestellt. Über den Button "Bearbeiten" kann ein Modul angepasst werden. Über den Button "Modul hinzufügen" können neue Module für eine Einreichung vorbereitet werden. Mit dem Button "Prüfe auf aktuellen Stand" wird automatisch geprüft welche Module aktuell auf dem aktuellen Stand des Hauptbranches des dazugehörigen Repositories sind. Diese Funktion wird nur für Repositories auf GitHub unterstützt. Bei einer größeren Anzahl von Modulen werden entsprechend viele Anfragen an die GitHub-API gemacht, welche ohne Verknüpfung mit einem GitHub-Benutzerkonto schnell aufgebraucht werden können. Wird das Konto des persönlichen Bereichs mit GitHub verbunden wird dieses Limit erheblich erhöht. Falls dem eigenen Konto Zugriff auf andere Konten gewährt wurde, können durch die Auswahl "Konto" die Einreichungen dieser Konten geprüft und bearbeitet werden.
Modul hinzufügen
Nach einem Klick auf "Modul hinzufügen" erscheint ein Dialog, in welchem eine Bundle ID und ein initialer Kanal ausgewählt wird.
Die Bundle ID ist eine eindeutige ID, welche auch bei neuen Versionen gleich bleibt, und aus Kleinbuchstaben und Punkten besteht. Es wird empfohlen die umgekehrte Domänennotation zu verwenden, z.B. de.symcon.alexa. Der initiale Kanal ist der Kanal für die erste Einreichung. Später können problemlos weitere Kanäle hinzugefügt werden.
Modul einreichen
Unter "Modul bearbeiten" kann man den aktuellen Status nach Kanälen prüfen und die nächste Einreichung vorbereiten.
Unter GIT-URL wird die Adresse des Git Repository eingetragen, unter welcher die aktuelle Bibliothek zu finden ist. Um private Repositories zu verwenden, muss das Konto des persönlichen Bereichs mit einem GitHub-Benutzerkonto verbunden werden, welches Zugriff auf das private Repository hat.
Aktuell werden private Repositories nur bei GitHub unterstützt.
Nach der URL wird der Commit ausgewählt, welcher veröffentlicht werden soll. Hierzu kann man auf das Zahnrad in der Zeile "GIT-Commit" klicken, den gewünschten Commit anklicken und per "Auswählen" bestätigen. Der Dialog bietet die Commits nach Branches aufgeteilt an. Wird der gewünschte Commit nicht angezeigt, können per "Mehr laden" mehr Commits eines Branches geladen werden. Alternativ kann die ID des Commits auch manuell eingegeben werden. Ist das Repository nicht bei GitHub ist der Dialog eingeschränkt und es kann lediglich ein Branch ausgewählt werden. Es wird automatisch der neueste Commit auf diesem Branch ausgewählt.
Eine Lokalisierung stellt Namen und Beschreibungen des Moduls in einer Sprache bereit. Es können mehrere Lokalisierungen für mehrere Sprachen hinzugefügt werden, mindestens eine ist allerdings erforderlich. Das Modul muss in allen lokalisierten Sprachen nutzbar sein. Wurde ein Modul einmal mit einer Lokalisierung veröffentlicht, so muss diese Sprache auch in zukünftigen Veröffentlichungen angeboten werden.
Durch einen Klick auf "Lokalisierung hinzufügen" öffnet sich ein Dialog in welchem die Sprache der neuen Lokalisierung ausgewählt werden kann.
Nachdem die Auswahl mit "OK" bestätigt wurde, erscheint eine neue leere Lokalisierung der ausgewählten Sprache. Mit einem Klick auf den Pfeil rechts kann eine Lokalisierung ausgeklappt werden.
Folgende Felder müssen für eine Lokalisierung ausgefüllt werden:
| Feld | Beschreibung |
|---|---|
| Name | Der angezeigte Name des Moduls |
| Beschreibung | Eine Beschreibung des Moduls |
| Versionsinformation | Informationen was zu dieser Version neu ist |
| Link zur Dokumentation | Ein Link zur Erklärung des Moduls. Dies kann beispielsweise eine Readme im Repository oder auch ein erklärender Beitrag im Forum sein |
Durch einen Klick auf das X neben der Sprache kann eine Lokalisierung wieder entfernt werden.
Abschließend werden passende Kategorien für die Einreichung ausgewählt. Über "Kategorie hinzufügen" erscheint ein Dialog in welchem eine neue Kategorie ausgewählt werden kann und mit "Auswählen" bestätigt wird.
Kategorien können durch einen Klick auf das dazugehörige X wieder entfernt werden. Für eine Einreichung ist mindestens eine Kategorie erforderlich, es dürfen aber auch mehr Kategorien sein.
Unter "Einreichung" können noch weitere Einstellungen vorgenommen werden.
| Einstellung | Beschreibung |
|---|---|
| Aktualisierung beinhaltet keine funktionalen Änderungen | Diese Einstellung kann aktiviert werden, wenn die aktuelle Einreichung keine für Benutzer relevanten programmatischen Änderungen beinhaltet und beispielsweise nur der Stil aktualisiert wurde. Die neue Version wird Benutzern nicht angeboten. Dies kann sinnvoll sein um nicht-funktionale Änderungen einzureichen, damit das Modul wieder auf aktuellem Stand erkannt wird |
| Schließe Beta- und Testing-Kanal nach erfolgreichem Review | Ist diese Einstellung aktiviert, werden nach erfolgreicher Veröffentlichung alle niedrigeren Kanäle geschlossen. Geschlossene Kanäle sind nicht mehr im Module Store verfügbar. Benutzer, die nun auf einem geschlossenen Kanal sind, werden für Aktualisierungen auf den nächsthöheren verfügbaren Kanal verwiesen. Existieren aktuell keine Veröffentlichung auf einem niedrigeren Branch, wird diese Einstellung nicht angezeigt |
Abschließend bietet die aktuelle Vorlage drei Buttons. Durch "Verwerfen" wird die Vorlage wieder gelöscht. Existiert von dem Modul nur die Vorlage, so wird damit das gesamte Bundle gelöscht. "Speichern" speichert den aktuellen Zustand der Vorlage. Hierfür müssen nicht alle Elemente ausgefüllt sein. Ein Modul ohne Lokalisierungen und Kategorien kann also gespeichert werden, aber nicht eingereicht. Per "Einreichen" reicht man das Modul zur Bereitstellung im Module Store ein. Auf den Kanälen Testing und Beta wird das Modul direkt im Module Store angeboten. Bei einer Einreichung auf Stable durchläuft das Modul vor der Veröffentlichung einen Reviewprozess durch das Symcon-Team. Wird das Modul angenommen, wird es im Module Store veröffentlicht. Wird es abgelehnt, wird man im Entwicklerbereich und per E-Mail benachrichtigt, warum es zur Ablehnung kam.
Review
Bei dem Review eines Moduls wird auf verschiedene Punkte auf Basis unser Best Practices geprüft. Dies sind inbesondere folgende Punkte:
- Greift das Modul auf lokale Dateien zu und könnte diese auslesen und manipulieren?
- Es ist in Ausnahmefällen genehmigt auf lokale Dateien zuzugreifen, insbesondere innerhalb des IP-Symcon-Ordners. Hier erfolgt allerdings eine genauere Prüfung um Missbrauch zu verhindern.
- Ist für jede Lokalisierung des Modules auch eine entsprechende Übersetzung vorhanden?
- Lassen sich die Instanzen des Moduls fehlerfrei erstellen, auch wenn möglicherweise nicht alle Anforderungen erfüllt sind?
- Ein Modul muss unter allen Umständen als Instanz erstellbar sein. Das Modul muss also selbstständig prüfen ob die Anforderungen erfüllt sind. Sind die Anforderungen nicht erfüllt, so soll dies geeignet in der Instanzkonfiguration dargestellt werden.
- Läuft eine eventuelle Kommunikation über Splitter/IO wie vorgesehen über den Datenfluss via SendDataToChildren/SendDataToParent/ReceiveData/ForwardData?
- Greift ein Modul nur auf eigene oder ihm zugewiesene Objekte zu?
- Eigene Objekte liegen unterhalb der Instanz.
- Per SelectVariable und ähnlichen Elementen können einem Modul weitere Objekte zugewiesen werden, welche im erwarteten Rahmen verwendet werden dürfen.
- Externe Objekte, welche dem Modul nicht zugewiesen wurden, dürfen nicht manipuliert werden.
- Neue Objekte dürfen außerhalb der Instanz nur erstellt werden, wenn dies explizit vom Benutzer bestätigt wurde. Ein konformes Beispiel hierfür ist die Verwendung des Konfigurationselements "Configurator".
- Dies verbietet auch die Erstellung von Ereignissen um interne Funktionen zu schalten. Hierfür sind RegisterTimer bzw. MessageSink und die dazugehörigen Funktionen zu verwenden.
- Abweichungen sind mit Absprache möglich. Dies sollte bei Einreichung allerdings an geeigneter Stelle erörtert werden, beispielsweise per E-Mail oder als Kommentar an der betroffenen Stelle im Code.
- Codequalität oder Fehlerfreiheit wird im Rahmen des Reviews nicht überprüft.
- "IPSymcon", "IPS" oder vergleichbares darf nicht Teil eines in einer Lokalisierung gewählten Namens sein.
- Module, die als Bedingung mehr als die aktuelle Stable-Version erfordern, also beispielsweise nur mit der aktuellen Beta funktionieren, dürfen nicht auf dem Stable-Kanal eingereicht werden.
- Einige Objekteigenschaften befinden sich auch bei moduleigenen Objekten in der Hoheit des Benutzers. Diese dürfen initial vorgegeben werden, aber ohne explizite Bestätigung des Benutzers nicht weiter manipuliert werden. Diese Eigenschaften sind:
- Der Name
- Alle visuellen Einstellungen: Objekt anzeigen, Objekt aktiv und Icon
- Die Beschreibung
- Die Position
- Alle ereignisspezifischen Eigenschaften
- Benutzerdefiniertes Profil, benutzerdefinierte Aktion und Logging von Variablen dürfen nie ohne explizite Bestätigung gesetzt werden, auch nicht initial! Aktion oder Profil können selbstverständlich über Standardaktion bzw. -profil definiert werden.
- PHP-Dateien dürfen nicht den kurzen PHP-Tag (<?) verwenden und sollten stattdessen den langen PHP-Tag (<?php) verwenden.
- Nach der initialen Erstellung einer Instanz liegt die Hoheit über die Eigenschaften beim Benutzer.
- Wenn das Modul hier etwas ändern möchte, so können andere Werte über die Dynamikfunktion UpdateFormField vorgegeben werden und dann vom Benutzer bestätigt werden.
- Somit sollten die Funktionen IPS_SetProperty und IPS_ApplyChanges nie verwendet werden.
- Wird bei einer List oder einem Tree der Parameter loadValuesFromConfiguration auf false gesetzt, so muss die Eigenschaft dennoch beim Laden im Sinne des Benutzers gefüllt werden. Der Parameter soll es lediglich ermöglichen beispielsweise die Reihenfolge anzupassen oder neue Werte mittig hinzuzufügen.
- Eine Einreichung benötigt einen sprechenden Namen, eine passende Beschreibung und Versionsinformation sowie eine Dokumentation, welche die Konfiguration und Verwendung des Moduls erklärt.
- Sind Konfiguratoren mit einem Splitter oder I/O verbunden, so dürfen sie nur Geräte verwalten, welche auch zu diesem Splitter bzw. I/O verbunden sind
- Instanzen, welche mit dem gleichen Splitter oder I/O wie der Konfigurator verbunden sind, sollen im Konfigurator aufgelistet werden, egal ob diese physikalisch noch existieren oder nicht
- Instanzen, welche mit einem anderen Splitter oder I/O verbunden sind, dürfen nicht in einem Konfigurator mit Splitter oder I/O aufgelistet werden
- Bietet ein Modul eine Discovery-Instanz an, so muss diese ohne Konfiguration funktionieren
- Da Logging problemlos via $this->LogMessage realisiert werden kann und diese Nachrichten korrekt mit der sendenden Instanz verknüpft sind, darf IPS_LogMessage nicht mehr zum Logging verwendet werden
Modul bearbeiten
Existiert unter "Modul bearbeiten" auf einem Kanal keine aktuelle Vorlage, so kann durch einen Klick auf "Neue Version vorbereiten" eine neue Vorlage erstellt werden. Im Dialog kann ausgewählt werden, ob man eine komplett neue Vorlage erstellt oder eine aktuelle Veröffentlichung als Vorlage verwenden möchte.
Alternativ ist bei Veröffentlichungen eine Option diese auf einen höheren Kanal zu ziehen vorhanden. Wurde eine Einreichung abgelehnt, so kann diese auch als neue Vorlage verwendet werden um erkannte Mängel auszugleichen ohne alles erneut zu konfigurieren.
Soll ein Modul, das sich aktuell im Review befindet, zurückgezogen werden, so kann dies durch einen Klick auf "Zurückziehen" getan werden. Befindet sich ein Modul im Module Store, so kann es nicht mehr zurückgezogen werden.
Mit GitHub verbinden
Das Konto des persönlichen Bereichs kann mit GitHub verknüpft werden. Dies ermöglicht zum einen die Verwendung von privaten Repositories sowie eine deutlich höhere Menge an Abfragen an die GitHub-API. Diese können insbesondere relevant werden, wenn die veröffentlichten Module auf aktuellen Stand geprüft werden sollen. Die Verknüpfung kann in den Einstellungen des persönlichen Bereichs durchgeführt werden. Dazu muss im Bereich "(Entwickler) GitHub OAuth Verbindung" auf "Verbinden" geklickt werden.
Sofern im Browser aktuell kein GitHub-Benutzer angemeldet ist, geschieht dies im nächsten Schritt. Hierzu müssen E-Mail-Adresse und Passwort des GitHub-Benutzerkontos eingegeben werden. Ist bereits ein Benutzer angemeldet, wird dieser Schritt automatisch übersprungen.
Abschließend muss der Zugriff durch Symcon autorisiert werden. Dies geschieht durch einen Klick auf "Authorize symcon".
Nun ist das Konto des persönlichen Bereichs mit dem GitHub-Benutzerkonto verknüpft. Um die Verbindung im Nachhinein wieder zu lösen, kann dies via Klick auf "Trennen" getan werden.