Einträge in MAINTAINER.txt

Begonnen von betateilchen, 28 August 2021, 12:37:25

Vorheriges Thema - Nächstes Thema

betateilchen

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.
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

rudolfkoenig

ZitatWenn 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.

Beta-User

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-elitedesk@Debian 12, 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: u.a MySensors, Weekday-&RandomTimer, Twilight,  div. attrTemplate-files

betateilchen

Zitat von: Beta-User am 29 August 2021, 07:48:41
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.
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

Beta-User

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-elitedesk@Debian 12, 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: u.a MySensors, Weekday-&RandomTimer, Twilight,  div. attrTemplate-files

betateilchen

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...
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

betateilchen

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.
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

Beta-User

Zitat von: betateilchen 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...
;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-elitedesk@Debian 12, 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: u.a MySensors, Weekday-&RandomTimer, Twilight,  div. attrTemplate-files

betateilchen

Zitat von: Beta-User am 30 August 2021, 12:43:00
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.
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

Otto123

Zitat von: Beta-User am 30 August 2021, 12:43:00
(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  ⇉  nächster Stammtisch an der Lindennaundorfer Mühle
RaspberryPi B B+ B2 B3 B3+ ZeroW,HMLAN,HMUART,Homematic,Fritz!Box 7590,WRT3200ACS-OpenWrt,Sonos,VU+,Arduino nano,ESP8266,MQTT,Zigbee,deconz

Beta-User

Zitat von: betateilchen am 30 August 2021, 12:53:53
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.

Zitat von: Otto123 am 30 August 2021, 13:02:10
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-elitedesk@Debian 12, 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: u.a MySensors, Weekday-&RandomTimer, Twilight,  div. attrTemplate-files

betateilchen

Zitat von: Beta-User am 30 August 2021, 13:14:37
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!

Zitat von: betateilchen am 30 August 2021, 09:56:10
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.)
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

Beta-User

Zitat von: betateilchen am 30 August 2021, 13:43:16
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-elitedesk@Debian 12, 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: u.a MySensors, Weekday-&RandomTimer, Twilight,  div. attrTemplate-files

betateilchen

#13
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
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

Beta-User

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-elitedesk@Debian 12, 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: u.a MySensors, Weekday-&RandomTimer, Twilight,  div. attrTemplate-files