Veröffentlichen eines Adapters

Bevor über das Veröffentlichen eines Adapters nachgedacht wird, sollte dieser im Forum Test Thread zum Testen angeboten werden. Sollten die Tests erfolgreich verlaufen und der Adapter stabil laufen, sollte dieser vorerst in das Latest-Repository aufgenommen werden.

Sollte der Adapter auf einer bestimmten Versionsnummer stabil laufen, darf dieser gerne in das Stable Repository überführt werden. Hierzu ist die Eigeneinschätzung des Entwicklers im Zusammenspiel mit den Nutzerrückmeldungen gefragt.

Weitere aktuelle Anforderungen finden Sie hier: https://github.com/ioBroker/ioBroker.repositories/blob/master/README.md

Anforderungen für das Latest Repository

Benutze https://adapter-check.iobroker.in/ um Adapter-Repo zu testen.
Das GitHub Repository des Adapters sollte ein großes B in ioBroker haben, während es in der package.json kleingeschrieben sein muss, da npm keine Großbuchstaben zulässt.
Der Titel in der io-package.json sollte nicht das Wort ioBroker und nicht das Wort Adapter enthalten.
Das title Attribut in der io-package.json (common) ist der Kurzname des Adapters auf Englisch. Während titleLang die Übersetzungen des title Attributes enthalten. (die Erweiterung Lang steht für languages)
Der Adapter sollte eine Anleitung in Form einer README.md Datei enthalten. Diese sollte mindestens in der englischen Sprache verfügbar sein. Ergänzend sind andere Sprachen willkommen. Als Anregung kann dieses Beispiel dienen.
Der Adapter benötigt eine Lizenz. Sowohl in der io-package.json als auch eine separate Datei im Github Repository.

Beispiel für io-package.json:
```
{
  "common": {
      "license": "MIT"
  }
}
```
Das www Verzeichnis sowie das widget Verzeichnis sollen bei Nichtnutzung gelöscht werden.
In der io-package.json sollte ein type Attribut unter common erstellt werden. Hierzu soll aus dieser Liste die best passende Kategorie angegeben werden.
In der io-package.json sollten die connectionType und dataSource Attributen unter common erstellt werden. Hierzu soll aus dieser Liste die best passende Verbindungs-Kategorie angegeben werden.
Die durch den Adapter erstellten States, sollten valide Angaben für ihre Rollen role unter common haben. Das Nutzen der Rolle state sollte vermieden werden.
Der Adapter muss die Tests aus dem Gerüst über GitHub Actions laufen lassen, mindestens Paket- und Integrationstest, also Installieren und Starten. Die Arbeitsabläufe dafür bringt der Adapter Creator bereits mit, sie liegen im Ordner .github/workflows. Weiteres unter Adaptertests.

Gerne kann der Testumfang durch den Entwickler erweitert werden.

In der io-package.json muss mindestens eine Angabe unter common für das Attribut authors gemacht werden. Ebenfalls muss das Attribut author in der package.json ausgefüllt sein. Optional können auch für npm mehrere Autoren hinterlegt werden, indem in der package.json das Attribut contributors genutzt wird.
Der Adapter muss als Paket auf npmjs.com veröffentlicht sein. Wie das geht, steht im nächsten Abschnitt.
Die ioBroker-Organisation muss Mitbesitzer des npm-Pakets sein:
```
npm owner add bluefox iobroker.<adaptername>
```
Das ist keine Formsache. Es sorgt dafür, dass das Paket weitergepflegt werden kann, wenn der Entwickler dazu keine Zeit mehr hat. Ohne diesen Eintrag wird der Adapter nicht aufgenommen.

Anforderungen für das Stable Repository

Der Adapter wurde erfolgreich in das Latest Repository aufgenommen
Es gibt einen Forum Test Thread für den Adapter, in welchem bereits Nutzerfeedback gegeben wurde.
Eine Discovery Funktion sollte implementiert werden. Hierbei handelt es sich um eine Funktion im Discovery Adapter, um automatisch zu erkennen, ob der Nutzer eine Instanz des Adapters gebrauchen kann. Hierzu ist ein Pull Request auf dem Repository des Discovery Adapters zu stellen.

Auf npm veröffentlichen

Bevor ein Adapter ins ioBroker-Repository kann, muss er auf npm liegen. Von dort holt ihn der Admin bei der Installation, nicht von GitHub.

Das Gerüst des Adapter Creators bringt dafür das release-script mit:

npm run release patch     # Fehlerbehebungen
npm run release minor     # neue Funktionen, abwärtskompatibel
npm run release major     # Änderungen, die Bestehendes brechen

Der Befehl erledigt in einem Zug, was sonst gern auseinanderläuft: er erhöht die Version in beiden Dateien, package.json und io-package.json, trägt die Änderungen aus dem Changelog in common.news ein, prüft die Lizenz, setzt ein Git-Tag und schiebt alles zu GitHub.

Der Arbeitsablauf in .github/workflows veröffentlicht daraufhin auf npm, sobald ein Tag ankommt. Von Hand geht es auch:

npm publish

?> Für die Veröffentlichung aus GitHub Actions heraus braucht es kein npm-Token mehr im Repository. npm unterstützt inzwischen Trusted Publishing: Das Paket wird auf npm mit dem GitHub-Repository verknüpft, und der Arbeitsablauf weist sich über OpenID Connect aus. Damit liegt kein dauerhaft gültiges Geheimnis mehr in den Repository-Einstellungen.

!> Nach dem Veröffentlichen ist die Version endgültig. Eine Version auf npm lässt sich nicht überschreiben, und ein npm unpublish ist nur in den ersten 72 Stunden möglich und macht die Versionsnummer trotzdem unbrauchbar. Lieber eine Version mehr als eine kaputte im Umlauf.

Hinzufügen des Adapters zum offiziellen Repository

Die Listen liegen im Repository ioBroker.repositories. Die Dateien werden nicht von Hand bearbeitet, dafür gibt es Skripte, die den Eintrag an die richtige Stelle setzen und gleich prüfen.

Das Repository abzweigen (fork) und örtlich klonen.
Den Eintrag erzeugen lassen:
```
npm run addToLatest -- --name <adaptername> --type <kategorie>
npm run addToStable -- --name <adaptername> --version <version>
```
Die Kategorie ist eine aus der Liste weiter unten, die Version bei stable die Versionsnummer, die stabil laufen soll.
Die geänderte Datei einchecken und einen Pull Request stellen.
Bei der Aufnahme in das Stable Repository muss eine Versionsnummer deklariert werden. Diese ist bei Weiterentwicklung des Adapters zu aktualisieren.
Der Adapter sollte in der io-package.json ein Listenattribut docs festlegen, unter der Angabe wo eine Anleitung in der jeweiligen Sprache zu finden ist. Als Key wird die Sprache angegeben und als Value der Pfad zur Markdown Datei. Eine englische Anleitung ist Pflicht (im Notfall kann auf die Standard README verwiesen werden). Ebenfalls ist eine deutsche Anleitung wünschenswert, da ein Großteil der Nutzer Deutsch spricht, jedoch ist dies optional. Eine ausführliche Anleitung kann dem Entwickler viel Zeit im Forum ersparen. Ein Beispiel kann hier gefunden werden.

Beispiel:
```
{
  "common": {
     "docs": {
         "de": "docs/de/README.md"
     }
  }
}
```

Latest

Die Datei sources-dist.json muss editiert werden:

Beispiel:

  "admin": {
    "meta": "https://raw.githubusercontent.com/ioBroker/ioBroker.admin/master/io-package.json",
    "icon": "https://raw.githubusercontent.com/ioBroker/ioBroker.admin/master/admin/admin.png",
    "published": "2017-04-10T17:10:21.690Z",
    "type": "general"
  }

Das published Datum stellt das Datum der Erstveröffentlichung dar und sollte nicht mehr geändert werden.

Stable

Die Datei sources-dist-stable.json muss editiert werden:

Beispiel:

  "admin": {
    "meta": "https://raw.githubusercontent.com/ioBroker/ioBroker.admin/master/io-package.json",
    "icon": "https://raw.githubusercontent.com/ioBroker/ioBroker.admin/master/admin/admin.png",
    "version": "2.0.7",
    "published": "2017-04-10T17:10:21.690Z",
    "type": "general"
  }

Das published Datum stellt das Datum der Erstveröffentlichung dar und sollte nicht mehr geändert werden.

Verwaltung von Adapterversionen

Die aktuelle Versionsnummer des Adapters wird sowohl in der io-package.json als auch in der package.json angegeben. Die beiden Angaben müssen übereinstimmen. Die Versionsnummer wird, durch zwei Punkte, in drei Teile separiert.

"version": "1.7.6"

Wobei der erste Teil (von links nach rechts) den Major Part darstellt, der zweite Teil den minor Part und der Letzte den micro Part. Die Versionsnummern sollten entsprechend folgender Liste erhöht werden:

micro: Es wurden lediglich Fehler behoben
minor: Es wurden Features hinzugefügt, jedoch ist die Version mit vorherigen Versionen kompatibel
major: Große Änderungen, durch die, die Abwärtskompatibilität zu alten Version nicht mehr gegeben ist

Ebenfalls sollte in der io-package.json das news Attribut gepflegt werden. Dies ermöglicht es Nutzern jede aufgelistete Version (unter der Voraussetzung, dass diese auf npm veröffentlicht wurde) über die Admin-Oberfläche zu installieren. Hierbei sollte die Versionsnummer sowie die Änderungen hinterlegt werden. Die Änderungen können für jede unterstütze Sprache dokumentiert werden, wobei diese mindestens auf Englisch angegeben sein sollten.

Beispiel:

"news": {
    "1.7.6": {
        "en": "Configuration dialog was corrected",
        "de": "Konfigurationsdialog wurde korrigiert",
        "ru": "Диалог конфигурации был исправлен",
        "pt": "A caixa de diálogo de configuração foi corrigida",
        "nl": "Configuratiedialoog is gecorrigeerd",
        "fr": "La boîte de dialogue de configuration a été corrigée",
        "it": "La finestra di configurazione è stata corretta",
        "es": "Se corrigió el diálogo de configuración",
        "pl": "Okno dialogowe konfiguracji zostało poprawione"
    },
    "1.7.5": {
        "en": "The roles were tuned",
        "de": "Die Rollen waren abgestimmt",
        "ru": "Роли были настроены",
        "pt": "Os papéis foram afinados",
        "nl": "De rollen zijn afgestemd",
        "fr": "Les rôles ont été réglés",
        "it": "I ruoli erano sintonizzati",
        "es": "Los roles fueron sintonizados",
        "pl": "Role zostały dostrojone"
    }
}

Adapterkategorien

alarm - Sicherheitssysteme
climate-control - Klimaanlagen, Luftfilter, Heizungen und mehr
communication - Datenbereitstellung für andere Adapter, z. B. per REST
date-and-time - z. B. Kalender
energy - Stromüberwachung, Solaranlagen, Wechselrichter uvm.
metering - Weitere Messsysteme (z. B. Wasser, Gas, Öl)
garden - z. B. Rasenmäher, Sprinkleranlagen
general - Generelle Adapter wie Admin, Web, Discovery
geoposition - Geolokalisierung von Objekten oder Personen
hardware - Unterschiedliche Multifunktionshardware wie Arduino, ESP, Bluetooth, ...
health - Blutdruck, Herzschlag, Körpergewicht, ...
household - Küchengeräte, Staubsauger, usw.
infrastructure - Netzwerk, NAS, Drucker, Telefone
iot-systems - Andere Smart Home Systeme (Hard- & Software)
lighting - Beleuchtungen
logic - Regeln, Skripte, Parser, usw.
messaging - Adapter zum Senden und Empfangen von Nachrichten z. B. via E-Mail, Telegram, ...
misc-data - Export und Import von Daten, Währungsrechner usw.
multimedia - TV, AVR, Boxen, Sprachassistenten usw.
network - Ping, Netzwerkerkennung, UPnP, ...
protocols - Kommunikationsprotokolle, z. B. MQTT
storage - Logging, Datenhaltung z. B. relationale Datenbanken, ...
utility - Unterstützende Adapter wie z. B. Backup
vehicle - Autos
visualization - Visualisierungsadapter, wie vis usw.
visualization-icons - Icons für Visualisierungen
visualization-widgets - iobroker.vis Widgets
weather - Wetterinformationen, Luftqualität, Umgebungsinformationen

Adapter Verbindungstyp

Definiere connectionType im common Teil von io-package.json als:

local - Bietet direkte Kommunikation mit dem Gerät oder Hub.
cloud - Die Integration dieses Geräts erfolgt über die Cloud und erfordert eine aktive Internetverbindung

Definiere dataSource im common als:

poll - Das Abfragen des Status bedeutet, dass ein Update möglicherweise später bemerkt wird.
push - ioBroker wird benachrichtigt, sobald ein neuer Status verfügbar ist.
assumption - Der Status des Geräts kann nicht ermittelt werden. ioBroker nimmt den Status basierend auf letzten ioBroker-Befehl.