Autor Thema: Einträge in MAINTAINER.txt  (Gelesen 1726 mal)

Offline betateilchen

  • Developer
  • Hero Member
  • ****
  • Beiträge: 17549
  • s/fhem\.cfg/configDB/g
Einträge in MAINTAINER.txt
« am: 28 August 2021, 12:37:25 »
Hallo liebe Entwicklerkolleg*innen,

in der MAINTAINER.txt macht sich langsam ein Wildwuchs an Eintragsformaten breit, der dem eigentlichen Nutzen dieser Datei entgegensteht.

Beispiele:

FHEM/_69_SoftliqCloud.pm     KernSani             Unterstützende Dienste
FHEM/73_DoorBird.pm          Sailor               https://forum.fhem.de/index.php/topic,100758
FHEM/59_Wunderground.pm      loredo               (deprecated)

Beim ersten Beispiel hoffe ich nur auf einen Tippfehler.

In einem Modul-Eintrag sollte keine URL ins Forum stehen, sondern der Name des Unterforums, in dem man Hilfe bekommt. URL funktionieren z.B. nicht bei "help <ModulName>"

Wenn ein Modul deprecated ist, sollte es nach ./contrib verschoben werden, für Module in contrib gibt es einen extra Bereich in der MAINTAINER.txt, dort kann man dann auch das deprecated vermerken, wenn man den Eintrag eines Moduls überhaupt noch für nötig erachtet.

Es wäre begrüßenswert, wenn wir wieder zum ursprünglichen "Standard" bei Einträgen in diese Datei zurückkommen würden.
-----------------------
Unaufgeforderte Anfragen per email werden von mir nicht beantwortet. Dafür ist das Forum da.
-----------------------
Lesen gefährdet die Unwissenheit!

Offline rudolfkoenig

  • Administrator
  • Hero Member
  • *****
  • Beiträge: 24686
Antw:Einträge in MAINTAINER.txt
« Antwort #1 am: 28 August 2021, 16:53:11 »
Zitat
Wenn ein Modul deprecated ist, sollte es nach ./contrib verschoben werden, für Module in contrib gibt es einen extra Bereich in der MAINTAINER.txt, dort kann man dann auch das deprecated vermerken, wenn man den Eintrag eines Moduls überhaupt noch für nötig erachtet.
Fuer mich ist ein deprecated Eintrag im MAINTAINER.txt ein Widerspruch.
Zustimmung Zustimmung x 2 Liste anzeigen

Offline Beta-User

  • Developer
  • Hero Member
  • ****
  • Beiträge: 16306
Antw:Einträge in MAINTAINER.txt
« Antwort #2 am: 29 August 2021, 07:48:41 »
Bekenne mich mal "schuldig", was die mehrfache Verwendung des 2. Typs angeht.

Werd's (ungern) für Twilight ändern, für die übrigen Fälle bin ich allerdings (aus unterschiedlichen Gründen) etwas zögerlich:
- ungern, weil: Es gibt diverse "uralt-Twilight"-Threads, die mich als neuen Maintainer eher nicht mehr interessieren. Nur wegen dieses (nunmehr hoffentlich wieder stabilen) Minimoduls den kompletten Forenbereich abonnieren zu "müssen", ist eher too much, ich fand die (bereits in der File zu findende) Idee ganz ok, den User gezielt auf den jeweils aktuellen Thread lotsen zu können, vor allem auch, ohne dass der vorher "das ganze Internet" gelesen haben muss (sondern ggf. nur den betreffenden Thread oder den/die ausdrücklich verlinkten Stellen im Forum/Wiki; ob das auf diesem Weg klappt, sei mal dahingestellt...);
- das obige gilt umso mehr für Codeschnipsel, die als "addons" zu attrTemplate ausgeliefert werden. Hat man so was, werden die ja auch via Help angezeigt. Macht dann vermutlich Sinn, direkt in einer noch zu erstellenden Kurzbeschreibung/im Wikitext zu Beginn direkt auf den betreffenden Thread zu verlinken, zu dem das gehört? Im Zweifel werfe ich den Bereich in diesen Fällen ganz raus, wenn es nicht gewünscht ist? Macht es halt für den Hilfesuchenden ggf. etwas schwerer, falls er überhaupt via MAINTAINER.txt sucht.
- bei den files, die gar nicht in help/der commandref landen (attrTemplate-files selbst) ist dann zwar meist ein "Info-Template" vorhanden, wo man die betreffenden Links (auch) findet, aber in diesen Fällen macht m.E. eigentlich nur ein copy/paste-fähiger Link (in MAINTAINER.txt) Sinn. Oder hat jemand bessere Ideen?

Generell fände ich es überlegenswert, sowas wie Direktlinks zu einzelnen Threads zu ermöglichen (bzw. besser auszuwerten und in help darzustellen), in welcher Form auch immer (ggf. als ergänzende Angabe). Kann aber sein, dass das dann wieder an anderer Stelle (Meta.pm?) Probleme verursacht (wenn dafür die Daten nicht separat angegeben wurden).
Server: HP-T620@Debian 10, aktuelles FHEM + ConfigDB | CUL_HM (VCCU) | MQTT2: MiLight@ESP-GW, BT@OpenMQTTGw | MySensors: seriell, v.a. 2.3.1@RS485 | ZWave | ZigBee@deCONZ | SIGNALduino | MapleCUN | RHASSPY
svn:MySensors, Weekday-&RandomTimer, Twilight,  AttrTemplate {u.a. mqtt2, mysensors, zwave}

Offline betateilchen

  • Developer
  • Hero Member
  • ****
  • Beiträge: 17549
  • s/fhem\.cfg/configDB/g
Antw:Einträge in MAINTAINER.txt
« Antwort #3 am: 30 August 2021, 09:56:10 »
Generell fände ich es überlegenswert, sowas wie Direktlinks zu einzelnen Threads zu ermöglichen (bzw. besser auszuwerten und in help darzustellen), in welcher Form auch immer

Vorschlag: setze den Link zu einem Forumthread hinter die Angabe des Unterforums, in dem das Modul behandelt wird.

FHEM/73_DoorBird.pm          Sailor               Sonstige Systeme       https://forum.fhem.de/index.php/topic,100758
Wenn solche Links einheitlich (!) an der 4. Stelle stehen, kann ich das in help entsprechend berücksichtigen.
-----------------------
Unaufgeforderte Anfragen per email werden von mir nicht beantwortet. Dafür ist das Forum da.
-----------------------
Lesen gefährdet die Unwissenheit!

Offline Beta-User

  • Developer
  • Hero Member
  • ****
  • Beiträge: 16306
Antw:Einträge in MAINTAINER.txt
« Antwort #4 am: 30 August 2021, 11:06:37 »
Danke, werde ich dann ggf. bei Gelegenheit bei den "speziellen Modulen" so einpflegen, bei denen das help/commandref-relevant ist; zum Rest (v.a. attrTemplate-files) werde ich mir nochmal Gedanken machen.

Habe eben mal getestet, u.a. weil es ja auch diverse (pm an ...)-Einträge gibt, die heute stressfrei via help angezeigt werden. Einen Eintrag in der Form
FHEM/59_Twilight.pm          Beta-User/orphan     Unterstützende Dienste/Wettermodule (Forum Thread #114061)akzeptiert help auch heute schon (ohne daraus einen Link zu machen).

Eventuell wäre das ein bereits ausreichender Weg, den (strukturiert suchenden) Hilfesuchenden den Weg (besser als bisher...) zu weisen?
Ein Link ist zwar "noch schöner", war aber auch bisher nicht vorhanden.

(Meta.pm habe ich der Hinsicht nicht angeschaut, gehe aber davon aus, dass derartige Klammer-Angaben auch da keine Problem verursachen, zumal man es da ja als Maintainer in der Hand hat, (gesondert) valide Daten vorzuhalten).

Aber unabhängig davon, wie man es am Ende konkret macht: Es sollte einheitlich sein!
Von daher warte ich jetzt erst mal noch ein Weilchen, ob es ggf. andere finale Vorgaben gibt.

Danke auf alle Fälle für's Anschubsen!
Server: HP-T620@Debian 10, aktuelles FHEM + ConfigDB | CUL_HM (VCCU) | MQTT2: MiLight@ESP-GW, BT@OpenMQTTGw | MySensors: seriell, v.a. 2.3.1@RS485 | ZWave | ZigBee@deCONZ | SIGNALduino | MapleCUN | RHASSPY
svn:MySensors, Weekday-&RandomTimer, Twilight,  AttrTemplate {u.a. mqtt2, mysensors, zwave}

Offline betateilchen

  • Developer
  • Hero Member
  • ****
  • Beiträge: 17549
  • s/fhem\.cfg/configDB/g
Antw:Einträge in MAINTAINER.txt
« Antwort #5 am: 30 August 2021, 12:11:04 »
Das Hauptproblem an Deinem Vorschlag sehe ich darin, dass 99% aller Nutzer vermutlich nicht wissen, wie sie aus der Nummer eines Threads zum Thread im Forum kommen...
-----------------------
Unaufgeforderte Anfragen per email werden von mir nicht beantwortet. Dafür ist das Forum da.
-----------------------
Lesen gefährdet die Unwissenheit!
Zustimmung Zustimmung x 2 Liste anzeigen

Offline betateilchen

  • Developer
  • Hero Member
  • ****
  • Beiträge: 17549
  • s/fhem\.cfg/configDB/g
Antw:Einträge in MAINTAINER.txt
« Antwort #6 am: 30 August 2021, 12:16:03 »
Man könnte ja auch in $hash eine "HelpURL" einfügen, die dann direkt in den Internals eines device angezeigt wird.
Damit käme man aus einem "Problem-Device" einfach in den entsprechenden Forumthread.
-----------------------
Unaufgeforderte Anfragen per email werden von mir nicht beantwortet. Dafür ist das Forum da.
-----------------------
Lesen gefährdet die Unwissenheit!
Gefällt mir Gefällt mir x 2 Liste anzeigen

Offline Beta-User

  • Developer
  • Hero Member
  • ****
  • Beiträge: 16306
Antw:Einträge in MAINTAINER.txt
« Antwort #7 am: 30 August 2021, 12:43:00 »
Das Hauptproblem an Deinem Vorschlag sehe ich darin, dass 99% aller Nutzer vermutlich nicht wissen, wie sie aus der Nummer eines Threads zum Thread im Forum kommen...
;D Na ja, genau die 99% werden auch nicht "help" aufrufen, um an die Info zu kommen... Im Ernst: es geht v.a. darum, nicht wieder versehentlich mit dem Hintern was einzureißen, also ist mir jeder Vorschlag willkommen, der uns weiterbringt.
Wer bei "help" angelagt ist, wird dann vielleicht wenigstens auch einen Link wahrnehmen, wenn der gleich in der Einleitung steht - so habe ich das jetzt in den meisten myUtils-Fällen gelöst, wenn auch (noch?) ohne ausdrückliche Anker-Angabe, es springt also nicht direkt ins Auge.

Das mit der HelpURL würde bei Twilight weiterhelfen, bei den myUtils zu den diversen MQTT2_DEVICE-addons ist das eher schwierig, weil für unterschiedliche Instanzen dann auch unterschiedliche URL's benötigt werden. Ist zwar möglich, aber es wird dann wieder ein Problem, sowas wie einen allgemeingültigen Standard rauszugeben.
In diesen Fällen dürfte es den meisten Usern auch relativ schnell entfallen, dass sie Zusatzfunktionen nutzen, und wo die herkommen (bzw. wo dann Hilfe/die commandref dafür zu finden ist). Da sehe ich künftig eher das Problem, dass jemand mal umzieht, und dann sowohl das addon fehlt wie die Hilfe dazu...

(Für diese Fälle wäre es mAn. klasse, die "originale commandref" des "gemoddeten Moduls" (im laufenden Betrieb) ergänzen zu können, aber das hatte Rudi bereits früher mal (aus nachvollziehbaren Gründen) für "zu speziell" befunden; hilft aber auch nicht, wenn man das addon "verloren" hat).

Kurzum: ich persönlich habe kein Problem (mehr) damit, dass da in MAINTAINER.txt im Moment nicht der volle Link stehen soll, supporte aber auch jeden anderen Verbesserungsvorschlag.
Server: HP-T620@Debian 10, aktuelles FHEM + ConfigDB | CUL_HM (VCCU) | MQTT2: MiLight@ESP-GW, BT@OpenMQTTGw | MySensors: seriell, v.a. 2.3.1@RS485 | ZWave | ZigBee@deCONZ | SIGNALduino | MapleCUN | RHASSPY
svn:MySensors, Weekday-&RandomTimer, Twilight,  AttrTemplate {u.a. mqtt2, mysensors, zwave}

Offline betateilchen

  • Developer
  • Hero Member
  • ****
  • Beiträge: 17549
  • s/fhem\.cfg/configDB/g
Antw:Einträge in MAINTAINER.txt
« Antwort #8 am: 30 August 2021, 12:53:53 »
Kurzum: ich persönlich habe kein Problem (mehr) damit, dass da in MAINTAINER.txt im Moment nicht der volle Link stehen soll,

Es geht nicht darum, dass nicht der volle Link in der Datei stehen soll, sondern nur darum, WO der steht.
Eine URL sollte nur nicht an der Stelle stehen, an der der Name eines Unterforum erwartet wird.

Deshalb mein Vorschlag oben, eine URL - falls erforderlich - zusätzlich zum Namen des Unterforums aufzuführen.
-----------------------
Unaufgeforderte Anfragen per email werden von mir nicht beantwortet. Dafür ist das Forum da.
-----------------------
Lesen gefährdet die Unwissenheit!

Offline Otto123

  • Tester
  • Hero Member
  • ****
  • Beiträge: 19682
  • schon mal restore trainiert?
    • Otto's Technik Blog
Antw:Einträge in MAINTAINER.txt
« Antwort #9 am: 30 August 2021, 13:02:10 »
(Für diese Fälle wäre es mAn. klasse, die "originale commandref" des "gemoddeten Moduls" (im laufenden Betrieb) ergänzen zu können, aber das hatte Rudi bereits früher mal (aus nachvollziehbaren Gründen) für "zu speziell" befunden; hilft aber auch nicht, wenn man das addon "verloren" hat).
Ich hoffe Udo verdreht jetzt nicht die Augen.
Die lokale commandref wird ja durch einen adäquaten commandref Abschnitt in der xxxmyUtils ergänzt. Dieser Abschnitt wird auch mit help xxxmyUtils ordentlich dargestellt. Der user muss nur drauf kommen ;)
Viele Grüße aus Leipzig
RaspberryPi B B+ B2 B3 B3+ ZeroW,HMLAN,HMUART,Homematic,Fritz!Box 7490+7412,WRT1900ACS-OpenWrt,Sonos,VU+,Arduino nano,ESP8266

Offline Beta-User

  • Developer
  • Hero Member
  • ****
  • Beiträge: 16306
Antw:Einträge in MAINTAINER.txt
« Antwort #10 am: 30 August 2021, 13:14:37 »
Deshalb mein Vorschlag oben, eine URL - falls erforderlich - zusätzlich zum Namen des Unterforums aufzuführen.
Auch das wäre für mich ok.

Ich hatte das vorhin mit dem aktuellen help-Modul getestet, und das führt halt _derzeit_ dazu, dass gar nichts mehr angezeigt wird. Wenn du das fixen willst, finde ich das sehr gut!
Mir ging es nur darum, dass wir dann nicht eine andere, neue Baustelle aufreißen (neben Meta.pm mag es weitere Stellen geben, in denen die Datei ausgewertet wird) und aufzuzeigen, dass es - für den Nutzerkreis, der help nutzt, oder die commandref findet - auch andere Methoden gibt, die "störungs- und änderungsfei" heute schon vorhanden sind.

Die lokale commandref wird ja durch einen adäquaten commandref Abschnitt in der xxxmyUtils ergänzt. Dieser Abschnitt wird auch mit help xxxmyUtils ordentlich dargestellt. Der user muss nur drauf kommen ;)
Soweit dürfte das allen klar sein (fyi: habe gestern noch diverse "summary" ergänzt, dann steht da auch in "modular" jeweils direkt etwas "mehr" im Gesamtüberblick).

Beim "Ergänzen" ging es ggf. darum, id's wie (Pseudo-) "MQTT2_DEVICE-set-sonos2mqtt-volume" ergänzen zu können, damit man bei einem sonos2mqtt-Device direkt auch unter dem setter in der Detailansicht einen _zu diesem konkreten Device_ passenden Eintrag angezeigt bekommt. (Schon klar, dass man die Frage stellen kann, ob man sowas braucht; hier ging es jetzt nur darum klarzustellen, wie es in etwa gemeint war).
Server: HP-T620@Debian 10, aktuelles FHEM + ConfigDB | CUL_HM (VCCU) | MQTT2: MiLight@ESP-GW, BT@OpenMQTTGw | MySensors: seriell, v.a. 2.3.1@RS485 | ZWave | ZigBee@deCONZ | SIGNALduino | MapleCUN | RHASSPY
svn:MySensors, Weekday-&RandomTimer, Twilight,  AttrTemplate {u.a. mqtt2, mysensors, zwave}

Offline betateilchen

  • Developer
  • Hero Member
  • ****
  • Beiträge: 17549
  • s/fhem\.cfg/configDB/g
Antw:Einträge in MAINTAINER.txt
« Antwort #11 am: 30 August 2021, 13:43:16 »
Ich hatte das vorhin mit dem aktuellen help-Modul getestet, und das führt halt _derzeit_ dazu, dass gar nichts mehr angezeigt wird. Wenn du das fixen willst, finde ich das sehr gut!

Wenn solche Links einheitlich (!) an der 4. Stelle stehen, kann ich das in help entsprechend berücksichtigen.

Mit Links in der "4. Spalte" sollte mit der eben eingecheckten help-Version auf jeden Fall der Forumname aus der 3. Spalte angezeigt werden.
Der Link wird erstmal (wie bisher) nicht angezeigt. (Muss mir erst überlegen, warum ich die Link-Anzeige seinerzeit explizit ausgebaut hatte.)
-----------------------
Unaufgeforderte Anfragen per email werden von mir nicht beantwortet. Dafür ist das Forum da.
-----------------------
Lesen gefährdet die Unwissenheit!

Offline Beta-User

  • Developer
  • Hero Member
  • ****
  • Beiträge: 16306
Antw:Einträge in MAINTAINER.txt
« Antwort #12 am: 30 August 2021, 14:03:14 »
Mit Links in der "4. Spalte" sollte mit der eben eingecheckten help-Version auf jeden Fall der Forumname aus der 3. Spalte angezeigt werden.
Tut es - zumindest in meinem Testsystem.

Zitat
Der Link wird erstmal (wie bisher) nicht angezeigt. (Muss mir erst überlegen, warum ich die Link-Anzeige seinerzeit explizit ausgebaut hatte.)
"Gefühlt" ist das (bezogen auf die Help-Variante) ein Rückschritt gegenüber der rein nummerischen Angabe (mit #1234 in Klammern). Wenn da bei help "irgendwas" steht, ist das zumindest ein relativ deutlicher Hinweis an den geneigten User, dass der betreffende Maintainer sich was spezielles gedacht hat; andernorts muss man (noch mehr) damit rechnen, dass es im sonstigen Text ggf. untergeht.
Innerhalb MAINTAINER.txt finde ich "Link als Klartext" die bessere Variante.

Nur als Rückmeldung, falls du Argumente für oder gegen den weiteren Umgang mit dem Link-Thema in help brauchst...
Server: HP-T620@Debian 10, aktuelles FHEM + ConfigDB | CUL_HM (VCCU) | MQTT2: MiLight@ESP-GW, BT@OpenMQTTGw | MySensors: seriell, v.a. 2.3.1@RS485 | ZWave | ZigBee@deCONZ | SIGNALduino | MapleCUN | RHASSPY
svn:MySensors, Weekday-&RandomTimer, Twilight,  AttrTemplate {u.a. mqtt2, mysensors, zwave}

Offline betateilchen

  • Developer
  • Hero Member
  • ****
  • Beiträge: 17549
  • s/fhem\.cfg/configDB/g
Antw:Einträge in MAINTAINER.txt
« Antwort #13 am: 30 August 2021, 14:17:18 »
Es steht Dir frei, die Thread-Nummer hinter den Forumnamen zu setzen.

FHEM/59_Twilight.pm          Beta-User/orphan     Unterstützende Dienste/Wettermodule (Forum Thread #114061)   https://forum.fhem.de/index.php/topic,114061.0.html
liefert in help

Module: 59_Twilight.pm Maintainer: Beta-User/orphan Forum: Unterstützende Dienste/Wettermodule (Forum Thread #114061)
Intern arbeitet help weiterhin nur mit drei Spalten (wegen Leerzeichen in Unterforumnamen), der Link am Ende der Zeile wird per regex (sucht nach http) entfernt.



Ohne http:// https:// funktioniert übrigens auch:

FHEM/59_Twilight.pm          Beta-User/orphan     Unterstützende Dienste/Wettermodule forum.fhem.de/index.php/topic,114061.0.html
liefert

Module: 59_Twilight.pm Maintainer: Beta-User/orphan Forum: Unterstützende Dienste/Wettermodule forum.fhem.de/index.php/topic,114061.0.html
« Letzte Änderung: 30 August 2021, 14:21:39 von betateilchen »
-----------------------
Unaufgeforderte Anfragen per email werden von mir nicht beantwortet. Dafür ist das Forum da.
-----------------------
Lesen gefährdet die Unwissenheit!

Offline Beta-User

  • Developer
  • Hero Member
  • ****
  • Beiträge: 16306
Antw:Einträge in MAINTAINER.txt
« Antwort #14 am: 30 August 2021, 14:25:33 »
Thx für die Hinweise; werde dann vermutlich für die "speziellen Fälle" die "extended version" mit Klammer und http und link in der commandref-Einleitung wählen. Mal schauen, wer sich dann meldet und Gründe hat, warum das auch nicht gut ist...
Server: HP-T620@Debian 10, aktuelles FHEM + ConfigDB | CUL_HM (VCCU) | MQTT2: MiLight@ESP-GW, BT@OpenMQTTGw | MySensors: seriell, v.a. 2.3.1@RS485 | ZWave | ZigBee@deCONZ | SIGNALduino | MapleCUN | RHASSPY
svn:MySensors, Weekday-&RandomTimer, Twilight,  AttrTemplate {u.a. mqtt2, mysensors, zwave}