Neuer Blogbeitrag: Monatsrückblick - Dezember 2025 🎄

[Mic]

@ldittmar sagte in Online Meeting für ioBroker Core/Dev/Admin November:

Verschobene Themen:

• Einheitliche Dokumentation, Vorschlag VUPress (carsten04)
• link Adapter settings to readme (Dutchman)

Folgend der Discord-Diskussion hier

und

möchte ich gerne zum Doku-Thema als Themen-Vorschlag ergänzen

• Einbettung Dokumentation (markdown) direkt in die Adapter-Settings je nach Konfig-Sprache (de/en...) (Mic)

Siehe mein Ansatz - Forum-Link.

[AggroRalf]

Hi,
das Thema Doku ist mittlerweile eigentlich in drei Punkten vertreten:

• Struktur und Integration (carsten04, Mic, Dutchman?)
• Tools (carsten04, Mic, AlCalzone)
• Übersetzungen (UncleSam)

Macht es nicht eher Sinn die Punkte mal zu Trennen und erstmal über die Basis, also die Struktur zu reden ?

Aktuell haben glaub 90% der Adapter nur eine Readme.MD in den Sprachen Englisch und oft auch Deutsch. In der Readme steckt die Beschreibung, die Konfig-Anleitung, das Changelog und die Lizenz, alles in einer Datei.

Das macht es nicht unbedingt übersichtlich. Um mal meinen "User-Blick" zu erklären:

• Vor Installation: Was macht der Adapter (Beschreibung), was kann man konfigurieren (gerne Screenshots)
• Bei Konfiguration: Möglichst direkter Zugriff auf Hilfe zur aktuellen Einstellung / Registerkarte, also aus dem Admin heraus
• Bei Update: Was hat sich geändert

Und das idealerweise in meiner Sprache.

Als IT'ler leide ich auch häufig unter dem Versuch, ein Problem einfach mal einem Tool zu erschlagen ... Leider wirds damit oft nicht besser, da die Struktur bzw. Prozesse einfach nicht stimmen ...

GRuss Ralf

[UncleSam]

@AggroRalf sagte in Online Meeting für ioBroker Core/Dev/Admin November:

Macht es nicht eher Sinn die Punkte mal zu Trennen und erstmal über die Basis, also die Struktur zu reden ?

Absolut richtig, die Übersetzungen lösen wir ganz am Schluss. Struktur und Tools können aber sehr wohl voneinander abhängig sein.

[AggroRalf]

Ich habe nochmal über das Thema Doku-Struktur für Adapter nachgedacht und hau jetzt einfach mal einen Vorschlag raus :-)

In der iopackage.json gibt es ja aktuell nur diesen Eintrag für die Doku:

"readme": "https://github.com/gaudes/ioBroker.fahrplan/blob/master/README.md",

Um mal bei meinem "User-Blick" (siehe oben) zu bleiben, könnte man das einfach erweitern:

"readme": {
    "overview": {
        "en": "https://github.com/gaudes/ioBroker.fahrplan/blob/master/README.md",
        "de": "https://github.com/gaudes/ioBroker.fahrplan/blob/master/README_DE.md",
        ...
    },
    "changelog": {
        "en": "https://github.com/gaudes/ioBroker.fahrplan/blob/master/CHANGELOG.md"
        "de": "https://github.com/gaudes/ioBroker.fahrplan/blob/master/CHANGELOG_DE.md",
        ...
    },
    "license": {
        "en": "https://github.com/gaudes/ioBroker.fahrplan/blob/master/LICENSE.md",
        "de": "https://github.com/gaudes/ioBroker.fahrplan/blob/master/LICENSE_DE.md",
        ...
    },
    "config": {
        "en": "https://github.com/gaudes/ioBroker.fahrplan/blob/master/doc/CONFIG.md",
        "de": "https://github.com/gaudes/ioBroker.fahrplan/blob/master/doc/CONFIG_DE.md",
        ...
    }
},

Der "Fallback" im Admin wäre dann einfach das bisherige.

Im Admin werden die einzelnen Abschnitte der Readme ja auch heute schon auf unterschiedliche Register (Info, Änderungsprotokoll, Lizenz) aufgeteilt.

Die neuen Dateien enthielten folgendes:

• readme / overview: Übersicht über Funktion des Adapters, Badges
• changelog: Änderungen in Versionen
• license: Lizenz (MIT oder so)
• config: Konfigurationsanleitung, verlinkt in Readme (für Ansicht über Git) und direkt in Adapter-Konfig über ?-Symbol aufrufbar in eingestellter und vorhandener Sprache, sonst Fallback auf Englisch

Neue Adapter (Adapter-Checker) müssten die Struktur haben und mindestens DE und EN mitbringen.

Der Aufwand für die Realisierung wäre für Entwickler kaum größer als heute. Die Anwender hätten aber die Möglichkeit einer zur eingestellten Sprache passenden Doku und direkten Zugriff auf eine Konfigurationsanleitung aus den Adapter-Einstellungen heraus.

Und wenn man das ganze jeweils noch mit einem Button im Admin für den direkten Aufruf von Weblate oder so versieht, würden dann vielleicht im Laufe der Zeit sogar die Übersetzungen für diese Dateien wachsen.

Manchem ist dies vielleicht schon zuviel, anderen zu wenig. Aber es wäre ein relativ einfach zu realisierender Vorschlag und hoffentlich ein Anfang für eine bessere Anwender-Dokumentation der Adapter.

[ldittmar]

Jetzt brauchen wie ein Termin: https://doodle.com/poll/38y8ixuw644xv524

[apollon77]

Hi Leute,

ich hätte noch ein Thema was ich gern rein bringen würde, aber auch gern den "Ownership" direkt abgeben würde ;-))

Richtet sich vor allem an die "Visu" Devs ...

Es gab in https://github.com/ioBroker/ioBroker.socketio/issues/34 eine Anfrage warum extendObject und delObject per socket.io nicht geht. Es gibt auch effektiv einen PR schon um das generell zu "ändern" von @foxriver76 (https://github.com/ioBroker/ioBroker.socketio/pull/35).

Bisher sind (und hier darf mit @Bluefox gern korrigieren) diese beiden Methoden aus Absicht nur für "socket.io im Admin" verfügbar. Wenn es das nicht wäre, wäre es in allen web-Hosted Adaptern (und eigenen socket.io Instazen) verfügbar - ohne das ein User davon weiss.
Wenn man jetzt die (sorry für die Formulierung im vorauss) blöden Nutzern ausgeht die ggf web Instanzen per Port-Weiterleitung ins Internet stellen oder irgendwie erreichbar machen, dann ist das sehr gefährlich weil plötzlich diese Funktionen verfügbar sind. Jemand kann also sehr einfach (vor allem bei Installationen wo web als Admin läuft wie fast überall) alles löschen oder kaputt machen.
Ich fühle mich irgendwie nicht wohl das einfach so ungeschützt auf zu machen.

Eine option einfach ein setting im Admin adapter zu haben wäre auch eine, obwohl man die mit ner dicken fetten roten blinkenden Warnungen versehen muss - wenn man das aber braucht damit bestimmte visus gehen ist es wieder blödsinn.

Mein Gefühl geht auch eher dahin das man bei Visus generell über den Schutz von "Edit" vs "Visu"-Modus nachdenken muss, oder ?!
Das würde ich gern mal diskutieren.

Ideen wären als Beispiel zu sagen "del/extend gehen nur wenn ein User aktiv authentifiziert wurde".

Ziel für eine DIskussion im Meeting wäre in meinen Augen ein gemeinsames Verständnis zu schaffen und idealerweise einen bzw eine Gruppe von Ownern zu finden die sich dieser "Security Challenge für Visu Adapter" mal widmen wollen ...

[Bluefox]

Ich möchte auch echarts vorstellen.

[sigi234]

@Bluefox sagte in Online Meeting für ioBroker Core/Dev/Admin 28.11 20:30:

Ich möchte auch echarts vorstellen.

Kann man den Adapter schon publizieren?

[arteck]

@ldittmar stimmt das datum .. 28.11 20:30... ich habe mir 18ten notiert ??

[UncleSam]

@arteck Mir war auch, Mittwoch 18.

[ldittmar]

Ihr habt Recht!! Im Text habe ich auch den 18. rein geschrieben, aber in der Überschrift nicht. :face_palm: Mea culpa!!

[arteck]

@ldittmar Steinigung am 18.11 um 20:25 möge sich der Herr im Vorhof einfinden zum am Pfahl binden.

das Weibsvolk kann schon mal mit Steinesammeln anfangen

[apollon77]

Aber nur Männer erlaubt bei der Steinigung ... ganz nach MP Manier ;-))

[Mic]

@apollon77 sagte in Online Meeting für ioBroker Core/Dev/Admin 18.11 20:30:

Hi Leute,

ich hätte noch ein Thema was ich gern rein bringen würde, aber auch gern den "Ownership" direkt abgeben würde ;-))
Richtet sich vor allem an die "Visu" Devs ...
Es gab in https://github.com/ioBroker/ioBroker.socketio/issues/34 eine Anfrage warum extendObject und delObject per socket.io nicht geht. Es gibt auch effektiv einen PR schon um das generell zu "ändern" von @foxriver76 (https://github.com/ioBroker/ioBroker.socketio/pull/35).

(Zitat gekürzt)

Hi @apollon77

Danke für's aufgreifen :-)

Leider kann ich heute nicht dabei sein (Family ruft ;) ).
Ich verstehe deine Bedenken sehr gut (VIS, offene Ports, ...), echt ein wichtiger Punkt.
Mein Use Case ist hier übrigens nicht VIS, sondern ein npm-Modul (https://github.com/Jey-Cee/iobroker-drones) zum Ablösen des Windows-Control-Adapters. Aber ich hatte da dann einen schnellen Workaround eingebaut: https://github.com/Jey-Cee/iobroker-drones/blob/a5472f070963e3add7d15cf1813de197e3726269/main.js#L301
Bei einem Einsatz von socket.io in einem npm-Modul (also nicht VIS etc.) wäre das wohl unproblematischer?

Wünsche euch viel Spaß und einen konstruktiven Austausch heute Abend!

[sigi234]

@ldittmar

Gibt es wo einen Bericht zum nachlesen?

[ldittmar]

@sigi234 Alles was besprochen wurde, habe ich als Stichpunkte ganz oben, unterhalb der Themen geschrieben.