SVN Nutzungsregeln

Um als Entwickler im SVN Beiträge einzuchecken und zu betreuen gibt es einige Regeln, die beachtet werden sollten (und tlw. müssen) um ein reibungsloses Miteinander zu gewährleisten. Diese Regeln werden hier dargestellt.

Organisatorisches

Wie bekomme ich einen Schreibzugriff auf das SVN?

Einen Schreibzugriff erhalten User, welche dauerhaft ein Modul entwickeln möchten und dies innerhalb der FHEM Community auch betreuen möchten. Generell gelten folgende Vorrausetzungen für einen SVN Account:

• eigenständige Weiterentwicklung des Moduls (Bugfixing, neue Features, Anpassungen an neue Features/API's)
• Support von Usern im FHEM-Forum zu Fragen des Moduls

Sollte dies der Fall sein, bitte eine Email an svn@fhem.de schicken mit den folgenden Infos:

• kurze Modulerklärung
• Link zum aktuellen Modul (FHEM Forum-Thread, ...)
• FHEM Forum Username
• SSH Public-Key zur Authentifizierung (siehe https://svn.fhem.de/)

Sofern alles passt, wird dem Username der Schreibzugriff gewährt und man kann sein Modul einchecken.

Welche Files darf ich bearbeiten, welche nicht?

Generell gilt, jeder bearbeitet nur Dateien, die er selber beigesteuert hat. Das Anpassen von fremdem Modulen ohne Einverständnis des Eigentümers ist strikt untersagt!

Im SVN gibt es die Datei MAINTAINER.txt in der die Zuständigkeiten für alle Module, Dateien und Verzeichnisse festgehalten sind.

Folgende Dateien dürfen von allen Entwicklern bearbeitet werden:

• CHANGED - kurz und knappe Einträge von nutzerrelevanten Änderungen an FHEM
• MAINTAINER.txt - Eintrag/Änderungen von EIGENEN!!! Modulen

Vorgehensweisen

Neues Modul

Bei einem neuen Modul gilt es zwischen zwei Ausgangsszenarien zu unterscheiden. Hierbei ist entscheiden, ob man bereits einen schreibenden Zugriff auf das FHEM SVN-Repository, sowie Zugang zum FHEM Developer Bereich im Forum besitzt, oder nicht.

Sollte man noch keinen Zugriff auf das FHEM SVN Repository haben, so kann man diesen per Mail beantragen (siehe dazu: Wie bekomme ich einen Schreibzugriff auf das SVN?). Dabei ist es hilfreich einen Link zu dem neuen Modul der Anmeldung beizufügen oder dem Forums-Beitrag in dem das Modul bereits durch einzelne User positiv getestet wurde. Genauere Hinweise welche Voraussetzungen für die Aufnahme als Modulentwickler gelten sind im Developer-Bereich im Forum dokumentiert.

Wer bereits einen Schreibzugriff auf das FHEM SVN-Repository besitzt, kann ein neues Modul selbstständig einchecken. Auch hier gelten die Hinweise für Entwickler aus dem Developer Bereich.

Eine Ausnahme bilden hier Module, die auf weitere Perl-Module/Dateien/Binaries angewiesen sind, welche demnach mit eingecheckt werden müssten. Da solche Konstellationen generell unerwünscht ist, sollte man entweder mit den Repository-Maintainern Kontakt aufnehmen um das weitere Vorgehen zu besprechen, oder besser ganz auf solche Abhängigkeiten verzichten.

Sobald man sein eigenes Modul erfolgreich eingecheckt hat, sollte man einen Beitrag im Forumsbereich Ankündigungen einstellen in denen man das neue Modul kurz vorstellt und evtl. eine kurze Einführung gibt. Eine Diskussion zu dem neuen Modul sollte jedoch in einem separaten Forumsbereich erfolgen.

Änderungen an fremden Modulen

Die Änderungen von fremden Modulen ist ohne Einverständnis des Maintainers (siehe MAINTAINER.txt) ausdrücklich NICHT GESTATTET! Wenn man eine Änderung vorschlagen möchte, bitte einen entsprechenden Diff (via svn diff zu der aktuellen Modul-Version aus dem SVN erstellen und im entsprechenden Forum-Board (siehe MAINTAINER.txt) als Patch-Vorschlag einreichen. Der entsprechende Maintainer wird den Vorschlag anschließend prüfen und ggf. einchecken.

Änderungen an eigenen Modulen

Änderungen an eigenen Module, für die man selbst Maintainer ist, kann man frei ins SVN einbringen. Eine Änderung sollte dabei vor einem Check-In in einer lokalen FHEM-Installation ausreichend auf Stabilität und Fehlerfreiheit geprüft sein. Ebenso sollte die commandref-Dokumentation entsprechend angepasst werden, damit der User ein neues Feature dort nachlesen kann.

Bei größeren bzw. umfangreichen Änderungen, sollte man einen Beitrag im Forumsbereich Ankündigungen einstellen in denen man die Änderungen kurz vorstellt und evtl. eine kurze Einführung gibt. Eine Diskussion zu den Änderungen sollte jedoch in einem separaten Forumsbereich erfolgen.

Generell sollte man immer vor einem Commit zuerst mittels svn diff prüfen, welche Änderungen genau zum Commit vorliegen. Erst wenn nach dem Durchsehen keine ungewollten Änderungen enthalten sind und alles vollständig enthalten ist, kann man den Commit mittels svn commit oder svn ci vornehmen.

Dadurch sollen ungewollte Änderungen an Fremd-Modulen/-Dateien vermieden werden.

Weitere Informationen und Hilfe zu SVN gibt es bspw. hier.

Technische Regeln

Um Änderungen an Modulen, als auch neue Module einchecken zu können, müssen ein paar Regeln beachtet werden. Dies dient der Sicherstellung eines gewissen Mindeststandards bei der Dokumentation der Entwicklungshistorie, sowie wichtigen Anforderungen an eine gültige Commandref-Dokumentation.

Falls diese nicht eingehalten werden, wird ein Commit verweigert. Die folgenden Regeln werden durch einen sogenannten pre-commit Hook automatisch beim einchecken geprüft. Sofern alles in Ordnung ist, wird der Vorgang erfolgreich durchgeführt.

Commit Message

Jeder Check-In im SVN muss eine Commit-Message enthalten in der eine kurz und knappe Beschreibung der durchgeführten Änderungen auf Englisch erfolgt. Dabei ist wichtig, dass zuerst das Modul angegeben wird, an dem die Änderung durchgeführt wurde. Anschließend erfolgt getrennt von einem Doppelpunkt die Kurzbeschreibung. Eine Commit-Message muss folgendem Format entsprechen:

<MODULNAME>:<BESCHREIBUNG>

Bsp:

FB_CALLLIST: don't create html code in readings when create-readings attribute is activated and number-cmd attribute is set.
10_ZWave.pm: implement sequential callbackId (Forum #50090)

Sollte ein Check-In in direktem Zusammenhang mit einem Forums-Beitrag sein, so sollte man diesen in Kurzform (Bsp: Angabe der Thread-ID) in der Commit-Message vermerken. Somit können andere aus der Commit-Message sofort die Diskussion im Forum finden um die Hintergründe zu einer bestimmten Änderung nachvollziehen zu können.

Wenn eine Commit-Message nicht diesem Format entspricht, wird ein Commit verweigert.

Nummernpräfix bei Modulen darf nicht "99" sein

Jedes FHEM-Modul muss im Dateinamen immer ein 2-stelliges Nummernpräfix enthalten. Diese Zahl war früher für die Reihenfolge der Prüfung der Client-Liste in zweistufigen Modulen zuständig. Heute besitzen die Modulnummern diese Funktion nicht mehr.

Das Präfix "99" hat aber eine besondere Eigenschaft. Alle Module die mit dem Präfix "99" versehen sind, werden beim Start von FHEM automatisch geladen. Dieses ist historisch bedingt um z.B. die 99_myUtils.pm immer zu laden.

Das Präfix "99" ist jedoch zur weiteren Verwendung gesperrt um ein automatisches Laden von weiteren Modulen zu verhindern. Generell werden in FHEM Module bei der erstmaligen Verwendung automatisch geladen.

Neue Module, die das Nummernpräfix "99" tragen (z.B. "99_MyModule.pm") werden beim Check-In zurückgewiesen.

CHANGED Eintrag

Ein Eintrag in der Datei CHANGED darf max. 80 Zeichen pro Zeile enthalten. Dies dient der Lesbarkeit der Änderungen in der FHEM-Oberfläche insbesondere auf kleinen Geräten. Sollten man Zeilen in CHANGED einzufügen, welche mehr als 80 Zeichen pro Zeile enthalten, wird ein Check-In verweigert.

Dies gilt aktuell nur für die Datei CHANGED. Als Zeichen dienen alle sichtbaren Zeichen, als auch jedes einzelne Leerzeichen. Tabulatoren sind hierbei verboten und werden beim Check-In ebenfalls zurückgewiesen.

commandref-Regeln

Jedes Gerätemodul welches eingecheckt wird, muss einen commandref-Beitrag enthalten (mindestens in Englisch). Dieser Abschnitt muss bestimmte Regeln erfüllen, um in das SVN gelangen zu können:

1. mindestens ein commandref-Beitrag auf Englisch (POD-Marker: #begin html sowie #end html). Ein Modul ohne einen commandref-Beitrag wird verweigert, da eine minimale Dokumentation Pflicht ist.
2. Es dürfen keine Windows-Zeilenumbrüche in dem Beitrag enthalten sein (CR+LF). Es dürfen nur UNIX-Zeilenumbrüche verwendet werden (LF). Viele Editoren wie bspw. Notepad++ bieten entsprechende Einstellmöglichkeiten um das Zeilenende-Format zu konfigurieren.
3. Nach dem einleitenden POD-Marker #begin html muss eine Leerzeile erfolgen. Dies gilt für alle weiteren Beiträge in anderen Sprachen (z.B. Deutsch: #begin html_DE).
4. Ein Anker im Format <a name="[Modulname]"> muss am Anfang eines jeden commandref-Beitrag vorhanden sein. Dies dient als Sprungmarke in der fertig generierten commandref.html um vom Inhaltsmenü zum entsprechenden Beitrag springen zu können. Ohne einen solchen Anker, kann man den Beitrag vom Inhaltsverzeichnis aus nicht erreichen.
5. 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.
6. Es muss eine Kurzbeschreibung mit dem POD-Marker =item summary vorhanden sein. Die Beschreibung darf nicht länger als 80 Zeichen sein und soll eine kurze Beschreibung geben, was dieses Modul steuern kann, bzw. wofür es verwendet wird. Es geht hierbei darum dem Nutzer einen groben Eindruck zu vermitteln, wofür dieses Modul gedacht ist. Eine Kurzbeschreibung für weitere Sprachen (z.B Deutsch mit =item summary_DE) ist optional, darf aber nicht die 80 Zeichen überschreiten.

Weitere Informationen zur Commandref gibt es im Artikel: Guidelines zur Dokumentation

SVN $Id$ Platzhalter

Jedes Geräte- oder Hilfsmodul was in /trunk/fhem/FHEM/ eingecheckt wird, muss einen gültigen $Id$ Platzhalter als Kommentar beinhalten. Dies dient der Versionsanzeige für den FHEM-Befehl version. Dieser Platzhalter wird durch SVN selbsttätig beim Check-In aktualisiert.

Dazu ist ein Kommentar im jeweiligen Modul als Kommentar notwendig. Am besten als Kopfzeile folgendes einfügen:

# $Id$

package main;

use strict;
use warnings;

...

Allerdings wird $Id$ jetzt noch nicht automatisch ersetzt. Dazu muss der Wert "Id" der SVN Property svn:keywords hinzugefügt werden. Dazu folgenden Befehl auf der Linux-Shell ausführen:

svn propset svn:keywords Id [Moduldatei]

Wenn man nun ein svn diff ausführt, sollte einem folgendes angezeigt werden:

Index: 10_MODULE.pm
===================================================================
--- 10_MODULE.pm     (revision 10608)
+++ 10_MODULE.pm     (working copy)

Property changes on: 10_MODULE.pm
___________________________________________________________________
Added: Id
## -0,0 +1 ##
+svn:keywords
\ No newline at end of property

Nun kann man das Modul einchecken. Beim Check-In wird dann der $Id$-Platzhalter durch beispielhaft folgende Zeile ersetzt:

# $Id: 10_MODULE.pm 10475 2016-01-12 18:51:31Z svn-username $

package main;

use strict;
use warnings;

...

Diese $Id$-Zeile ist wichtig, denn sie dient dem FHEM-Kommando version als Grundlage um die Version aller Module zu ermitteln. Ein Modul welches entweder den Platzhalter als Kommentar nicht beinhaltet, oder die SVN-Property svn:keywords nicht angepasst hat, wird beim Check-In verweigert und abgelehnt.

Commit Befehl im Terminal

Beispiel:

cd /opt/fhem
svn commit -m "XX_YYYYY.pm: was_wurde_geändert (Forum #12345)" FHEM/XX_YYYYY.pm