Hinweise für Entwickler

[Dr. Boris Neubert]

Schreibrechte in diesem Board sind nicht gleichbedeutend mit Schreibrechten im SVN-Repository auf http://svn.fhem.de. Diese sind gesondert per E-Mail an den SVN-Administrator (svn@fhem.de) unter Angabe des Forum-Benutzernamens zu beantragen, siehe dazu bitte zuerst diese Hinweise.

Voraussetzung für die Erteilung der Schreibrechte in diesem Board wie auch für das SVN-Repository ist die Bereitschaft, sich längerfristig im FHEM-Entwicklerteam zu engagieren. Dies beinhaltet z.B. die Bereitstellung und nachhaltige Pflege neuer Module inklusive Dokumentation oder die Mitarbeit zur Weiterentwicklung bestehender Module.

Ein paar Regeln zum Umgang mit dem Kode im SVN-Repository, der uns Entwicklern die Zusammenarbeit erleichtert:

• Ändere bitte nur Deinen eigenen Kode. Für Änderungen an Modulen anderer Entwickler sende bitte Patches in dem jeweils zutreffenden Board.
• Einzelne Codebeiträge zu bestehenden Modulen bitte über Patches im zugehörigen Board posten.
• Einmalbeiträge von Modulen können unter dem contrib-Verzeichnis aufgenommen werden.
• Wenn Du ein Modul beisteuerst, dann trage Dich bitte in der Datei MAINTAINER ein.
• Ankündigungen neuer Module können in das Board Ankündigungen, Hinweise zu Anpassungen in die modulspezifischen Boards.
• Pflege bitte die CHANGED-Datei, wenn Du etwas änderst, was voraussichtlich größere Auswirkungen haben wird. Kleine Fixes und Doku-Updates brauchst Du nicht zwingend zu vermerken.
• Bitte sende bei Commits ins SVN-Repository einen englischsprachigen Kommentar mit.
• Die Kommentare beim Commit werden automatisch im Board "FHEM Code Changes" gepostet. Außerdem wird die Datei http://fhem.de/SVNLOG automatisch täglich generiert.
• Schau Dir bitte auch das FHEM-Wiki an.

Details zu den erzwungenen Regeln bei Commits findest Du in einem weiteren Beitrag.

[Dr. Boris Neubert]

Um das in diesem Developer-Board generierte Wissen zu verstetigen, bitten wir alle Entwickler, die hier eine Frage stellen und diese beantwortet bekommen, die  erhaltenen Information im FHEM-Wiki zu dokumentieren.

Danke
Boris

[Markus Bloch]

Um einen erfolgreichen Beitrag im SVN einzuchecken, sind einige Regeln einzuhalten, welche beim Commit geprüft werden. Sollte diese Regeln nicht befolgt werden, wird ein Commit abgelehnt (via pre-commit hook).

Folgende Regeln sind daher zu beachten:


1. SVN Commit Message - Sobald ein Beitrag im SVN eingecheckt wird, muss die Commit Message im Format [Modulname]:[Änderungsbeschreibung] sein. Am Anfang steht der Modulname oder Dateiname, an dem die Änderung durchgeführt wird, danach folgt ein Doppelpunkt zur Separierung und anschließend eine kurze und knappe Beschreibung der Änderung, so dass andere Entwickler eine grobe Vorstellung davon erhalten, was, wo geändert wurde. Eine SVN Commit Message ohne Doppelpunkt wird nicht akzeptiert und zurückgewiesen.

2. CHANGED Datei max. 80 Zeichen pro Zeile - Sollte der Commit Änderungen enthalten, welche für Endnutzer relevant sind, so muss dies in der Datei CHANGED dokumentiert sein. Um diese Datei auch auf kleinen Bildschirmen (Handy, Tablet, etc.) lesbar zu halten, dürfen Einträge nicht länger als 80 Zeichen pro Zeile sein (Leerzeichen/Tabulatoren mitgerechnet). Sollte durch einen Commit eine Zeile hinzugefügt werden, welche länger als 80 Zeichen ist, wird der Commit abgelehnt.

3. CHANGED Datei darf keine Tabulatorzeichen enthalten  - Um die Lesbarkeit und die Formatierung zu erhalten, dürfen keine Tabulatoren in der Datei CHANGED verwendet werden, um Zeilen einzurücken. Da Tabulatoren je nach Gerät eine unterschiedliche Anzahl an Leerzeichen darstellen, kann die Einrückung dadurch unterschiedlich ausfallen. Sollte durch einen Commit ein Tabulator in der Datei CHANGED hinzugefügt werden, wird der Commit abgelehnt.

4. SVN Platzhalter "$Id$" muss in Perl-Modulen vorkommen und aktiviert sein - Um ein Gerät- oder Hilfsmodul einchecken zu können, muss in den Kopfzeilen in Form eines Kommentars der Platzhalter $Id$ vorhanden sein. Des weiteren muss der Wert "Id" als SVN-Property svn:keywords gesetzt sein. Dies geschieht mit dem Befehl svn propset svn:keywords Id [Moduldatei]. Damit wird der Platzhalter $Id$ aktiviert und beim Einchecken durch SVN durch die aktuelle Revision, Zeitpunkt und Autor automatisch ersetzt. Sollte ein Perl-Modul entweder den Platzhalter $Id$ oder "Id" in svn:keywords nicht enthalten oder beides, so wird ein Commit abgelehnt.

5. commandref muss mindestens englischen Beitrag enthalten - Die Moduldokumentation (commandref) eines Moduls, welche direkt im Modul enthalten ist, muss mindestens einen englischen commandref-Beitrag enthalten (POD-Marker: =begin html und =end html). Eine Modul ohne jegliche Dokumentation in Englisch wird als offizielles Modul nicht akzeptiert. Zusätzliche Sprachen wie Deutsch sind optional und müssen nicht vorhanden sein. Ein Commit eines Moduls ohne englische commandref wird daher abgelehnt.

6. commandref nicht mit Windows Zeilenumbruch (CR+LF) - Die commandref darf keine Windows-Zeilenumbrüche (CR+LF; in Perl: \n\r) enthalten. Generell wird ausdrücklich empfohlen ALLE Dateien mit UNIX Zeilenumbrüchen (LF) zu erstellen und einzuchecken. Sollte durch einen Commit ein Modul mit Windows-Zeilenumbrüchen in der commandref versucht werden einzuchecken, wird dies abgelehnt.

7. Nach =begin html in commandref muss eine Leerzeile folgen - Wenn man in einem Modul die commandref-Dokumentation erstellt, muss nach dem einleitenden POD Marker =begin html (gilt für alle Sprachen) eine Leerzeile folgen. Es ist nicht erlaubt, den POD Marker zu setzen und auf der Folgezeile sofort mit HTML zu beginnen. Sollte ein Modul keine Leerzeile nach diesem einleitenden POD Marker enthalten, wird der Commit abgelehnt

8. commandref muss <a id="[Modulname]"> enthalten - Um in der commandref die einfache Navigation von der Modulübersicht zum eigentlichen Modulbeitrag zu gewährleisten, muss jeder commandref-Beitrag in einem Modul zu Beginn einen Anker mit seinem eigenen Modulnamen setzen. Ist dieser nicht vorhanden, kann der User nicht von der Modulübersicht zum Modulbeitrag navigieren. Enthält die Commandref keinen Anker, wird der Commit abgelehnt

9. commandref HTML Syntax muss korrekt sein - Vor dem einchecken eines Moduls mit commandref sollten insbesondere bei Änderungen an der commandref dieses vorher mittels commandref_join.pl auf evtl. Fehler im Bezug auf das eigene Modul getestet werden. Sollten dort bei der Erstellung der commandref-HTML-Dateien eine Warnung erscheinen, so wird das Modul beim Commit verweigert werden, da die selben Prüf-Mechanismen beim Commit durchlaufen werden. Dies gilt insbesondere für HTML-Tag-Balance. Ein Modul, welches Fehler bei commandref_join.pl erzeugt, wird beim Commit verweigert.

10. commandref muss mind. eine Kurzbeschrebung via =item summary enthalten - Um in der Modulübersicht der commandref ein grobes Verständnis über das Modul und deren Zweck zu geben, ist eine Kurzbeschreibung (mind. auf Englisch) durch den POD-Marker =item summary anzuzeigen. Die eigentliche Kurzbeschreibung folgt direkt hinter dem POD-Marker auf gleicher Zeile. Die Beschreibung darf nicht länger als 80 Zeichen sein, um die Modulübersicht nicht zu sprengen. Eine deutsche Kurzbeschreibung kann mit dem POD-Marker =item summary_DE eingefügt werden. Es muss mindestens eine englische Kurzbeschreibung enthalten sein, die nicht 80 Zeichen überschreitet. Ist dies nicht der Fall, wird der Commit abgelehnt.

Die Regeln 4 - 10 gelten nur für Module (*.pm), die in trunk/fhem/FHEM/ eingecheckt werden. Unterordner sind davon nicht betroffen.

Sollte ein Modulbeitrag all diesen Regeln entsprechen, so wird der Commit ins SVN zugelassen. Bei Verletzung dieser Regeln wird der Commit verweigert und eine entsprechende Fehlermeldung mit den Gründen ausgegeben.

Weiterführende Erklärungen zum Thema SVN Nutzungsregeln gibt es unter: https://wiki.fhem.de/wiki/SVN_Nutzungsregeln