SVN Nutzungsregeln

Todo: Dieser Artikel ist noch im Aufbau - bitte Verständnis für Unvollständigkeiten und fehlende Bereiche

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 direkten Kontakt mit Rudolf König oder Dr. Boris Neubert aufnehmen mit folgenden Infos:

• kurze Modulerklärung
• Link zum aktuellen Modul (FHEM Forum-Thread, ...)
• SourceForge Username
• FHEM Forum Username

Sofern alles passt, wird dem SourceForge 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 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

Ä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 dann entsprechend 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.

Technische Regeln

Um Änderungen an Modulen, als auch neue Module einchecken zu können, müssen ein paar Regeln beachtet werden. Falls diese nicht eingehalten werden, wird ein einchecken 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.

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.

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.