Feedback senden! (Bearbeiten)

Einreichen

Beschreibung

Soll eine entwickelte Bibliothek im Module Store angeboten werden, so muss dies über den Entwicklerbereich auf der Accountseite eingereicht werden.

Entwicklerbereich

Der Entwicklerbereit ist auf der Accountseite unter "Entwicklerbereich" zu erreichen.

Hier werden alle bisherigen Einreichungen aufgelistet und können über den Button "Bearbeiten" angepasst werden. Über den Button "Modul hinzufügen" können neue Module für eine Einreichung vorbereitet werden. 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.

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.

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.

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:

1. 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.
2. Ist für jede Lokalisierung des Modules auch eine entsprechende Übersetzung vorhanden?
3. 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.
4. Läuft eine eventuelle Kommunikation über Splitter/IO wie vorgesehen über den Datenfluss via SendDataToChildren/SendDataToParent/ReceiveData/ForwardData?
5. 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.
6. 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.
7. 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.
8. Codequalität oder Fehlerfreiheit wird im Rahmen des Reviews nicht überprüft.
9. "IPSymcon", "IPS" oder vergleichbares darf nicht Teil eines in einer Lokalisierung gewählten Namens sein.
10. 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.
11. 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.
12. PHP-Dateien dürfen nicht den kurzen PHP-Tag (<?) verwenden und sollten stattdessen den langen PHP-Tag (<?php) verwenden.
13. Nach der initialen Erstellung eine 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.
14. Eine Einreichung benötigt einen sprechenden Namen, eine passende Beschreibung und Versionsinformation sowie eine Dokumentation, welche die Konfiguration und Verwendung des Moduls erklärt.
15. Verwendet eine List oder ein Tree den Parameter noValuesFromConfiguration, so müssen die values des Elements im Sinne der gespeicherten Eigenschaft gefüllt werden. Dies soll beispielsweise das nachträgliche Hinzufügen oder Entfernen von Zeilen in einer konstanten Liste ermöglichen.
16. 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
17. Bietet ein Modul eine Discovery-Instanz an, so muss diese ohne Konfiguration funktionieren
18. 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.