homeESS ist ein offenes Projekt und Beiträge aus der Community sind willkommen.

Diese Richtlinien beschreiben, wie Änderungen, Fehlerbehebungen, neue Funktionen, Dokumentation und andere Beiträge zum homeESS-Projekt eingebracht werden können.

Für eigenständige Adapter sowie für Beiträge zu hDP gelten teilweise abweichende Regeln, die nachfolgend ausdrücklich beschrieben werden.

Bevor du beginnst

Kleinere Fehlerbehebungen oder offensichtliche Korrekturen können direkt vorbereitet werden.

Bei größeren Änderungen am homeESS-Kern sollte zunächst ein GitHub-Issue erstellt werden.

Das gilt insbesondere für:

• neue Kernfunktionen
• größere Änderungen an bestehenden Funktionen
• neue Module
• Änderungen an zentralen Datenstrukturen
• Erweiterungen der öffentlichen API
• grundlegende Änderungen der Benutzeroberfläche
• Änderungen mit Auswirkungen auf bestehende Installationen
• Vorschläge für Änderungen an hDP

So kann vor Beginn der eigentlichen Entwicklung geklärt werden, ob eine Änderung zur bestehenden Architektur passt und wie sie sinnvoll umgesetzt werden kann.

→ GitHub Issues öffnen

Fehlerbehebungen

Bugfixes am homeESS-Kern sind willkommen.

Ein guter Fehlerbeitrag sollte möglichst:

• das Problem klar beschreiben
• die Ursache beheben statt nur Symptome zu umgehen
• bestehende Funktionen nicht unnötig verändern
• keine unabhängigen Änderungen enthalten
• nach Möglichkeit reproduzierbar getestet sein

Wenn bereits ein Issue für den Fehler existiert, sollte der Pull Request darauf verweisen.

Neue Funktionen im homeESS-Kern

Neue Funktionen sollten einen nachvollziehbaren Anwendungsfall lösen und zur bestehenden Architektur von homeESS passen.

Dabei sollte geprüft werden, ob die gewünschte Funktion:

• für mehrere Nutzer sinnvoll ist
• bereits mit vorhandenen Strukturen umgesetzt werden kann
• besser als Kernfunktion, Modul oder externe Integration aufgehoben ist
• vorhandene Funktionen unnötig dupliziert
• langfristig wartbar bleibt

Nicht jede individuelle Spezialanforderung muss Bestandteil des homeESS-Kerns werden.

Adapter sind eigenständige Anwendungen

Adapter für homeESS sind grundsätzlich eigenständige Anwendungen.

Sie kommunizieren über die dokumentierte Adapter-API mit homeESS und müssen nicht Bestandteil des homeESS-Quellcodes sein.

Entwickler können deshalb eigene Adapter unabhängig vom homeESS-Projekt:

• entwickeln
• veröffentlichen
• weitergeben
• kommerziell anbieten
• unter einem eigenen Lizenzmodell vertreiben

Die Entscheidung über das Lizenzmodell eines eigenständigen Adapters liegt beim jeweiligen Entwickler.

Voraussetzung für die Integration ist, dass der Adapter die jeweils gültige Adapterrichtlinie und die dokumentierten Schnittstellen von homeESS einhält.

→ Adapterrichtlinie und API Dokumentation ansehen

Keine Änderungen am homeESS-Kern für einzelne Adapter

Ein einzelner Adapter darf keine Änderung des homeESS-Kerns voraussetzen.

Adapter müssen die bestehenden:

• Schnittstellen
• States
• Datenstrukturen
• Konfigurationsmechanismen
• Adapter-APIs

verwenden.

Herstellerspezifische Sonderfälle dürfen nicht direkt in homeESS eingebaut werden, nur um eine einzelne Integration zu ermöglichen.

Der homeESS-Kern soll herstellerneutral bleiben.

Erweiterungen der Adapter-API

Sollte sich bei der Entwicklung eines Adapters zeigen, dass eine allgemein sinnvolle Funktion in der Adapter-API fehlt, kann eine entsprechende Erweiterung vorgeschlagen werden.

Eine API-Erweiterung sollte nicht ausschließlich einen einzelnen Hersteller oder ein einzelnes Gerät bedienen, sondern die Adapterintegration allgemein verbessern.

Vorschläge können über:

• GitHub Issues
• Pull Requests

eingereicht und gemeinsam diskutiert werden.

Eine solche Erweiterung wird als Änderung von homeESS betrachtet und muss entsprechend zur bestehenden Architektur und zu anderen Adaptern passen.

Beiträge zum homeESS-Quellcode

Änderungen am homeESS-Kern werden über Pull Requests eingereicht.

Dazu gehören beispielsweise:

• Fehlerbehebungen
• neue allgemeine Funktionen
• Optimierungen
• Verbesserungen der Benutzeroberfläche
• Erweiterungen vorhandener Module
• Erweiterungen der öffentlichen API
• Tests
• Dokumentationsänderungen

Ein Pull Request sollte möglichst:

• eine klar abgegrenzte Änderung enthalten
• einen verständlichen Titel besitzen
• Zweck und Nutzen der Änderung erklären
• zugehörige Issues verlinken
• keine unnötigen Formatierungsänderungen enthalten
• unabhängige Funktionen nicht miteinander vermischen

Größere, voneinander unabhängige Änderungen sollten nach Möglichkeit in getrennten Pull Requests eingereicht werden.

Änderungen nachvollziehbar halten

Code sollte so umgesetzt werden, dass er auch später noch verständlich und wartbar bleibt.

Dabei gelten insbesondere folgende Grundsätze:

• vorhandene Projektstrukturen verwenden
• bestehende Namenskonventionen beibehalten
• unnötige Abhängigkeiten vermeiden
• keine Secrets oder persönlichen Daten einchecken
• keine generierten oder temporären Dateien committen
• bestehende Architektur nicht ohne nachvollziehbaren Grund umgehen

Wenn eine bestehende Struktur erweitert werden muss, sollte der Grund dafür im Pull Request beschrieben werden.

Bestehendes Verhalten nicht unnötig brechen

homeESS wird in realen Installationen eingesetzt.

Änderungen sollten deshalb möglichst abwärtskompatibel bleiben.

Besondere Vorsicht ist erforderlich bei:

• gespeicherten Konfigurationen
• Datenbankstrukturen
• States und State-Pfaden
• öffentlichen APIs
• Adapter-Schnittstellen
• Automationen
• bestehenden Geräteprofilen

Ist eine inkompatible Änderung erforderlich, sollte sie vor der Implementierung abgestimmt und im Pull Request deutlich dokumentiert werden.

Beiträge zu hDP

hDP ist offen dokumentiert, aber nicht frei lizenziert

Das homeESS Device Protocol (hDP) ist öffentlich dokumentiert.

Die offene Dokumentation dient dazu, die technische Funktionsweise nachvollziehbar zu machen und kompatible Implementierungen zu ermöglichen.

Das bedeutet jedoch nicht, dass hDP gemeinfrei oder frei von Lizenzbedingungen ist.

Die vollständigen Rechte am:

• hDP-Protokoll
• hDP-Namen
• hDP-Logo
• eigenständigen hDP-Adapter
• offiziellen hDP-Firmware

bleiben beim jeweiligen Rechteinhaber.

Diese Bestandteile unterliegen einem eigenen Copyright und sind nicht automatisch Bestandteil der Lizenzierung des homeESS-Kerns.

Freie Nutzung für den Eigenbedarf

Das hDP-Protokoll, der eigenständige hDP-Adapter und die offizielle hDP-Firmware dürfen für den Eigenbedarf frei und uneingeschränkt verwendet werden.

Dies umfasst insbesondere:

• private Nutzung
• eigene Installationen
• Entwicklung eigener Geräte für den Eigenbedarf
• Tests
• Experimente
• interne Nutzung ohne Vermarktung

Eine kommerzielle Nutzung oder Vermarktung kann dagegen zusätzlichen Lizenzbedingungen unterliegen.

→ hDP für Hersteller

Änderungen an hDP können vorgeschlagen werden

Auch Änderungen oder Erweiterungen des hDP-Protokolls können vorgeschlagen werden.

Da hDP jedoch eine definierte Kommunikationsschnittstelle zwischen Geräten und homeESS darstellt, können Änderungen weitreichende Auswirkungen auf bestehende Geräte, Firmware und zukünftige Kompatibilität haben.

Vorschläge sollten deshalb zunächst über ein GitHub-Issue beschrieben und begründet werden.

Dabei sollte insbesondere erläutert werden:

• welches Problem gelöst werden soll
• warum die bestehende Spezifikation dafür nicht ausreicht
• welche Geräte oder Anwendungsfälle betroffen sind
• welche Auswirkungen auf bestehende Implementierungen zu erwarten sind
• wie die Abwärtskompatibilität behandelt werden soll

Die Entscheidung über eine Änderung der offiziellen hDP-Spezifikation liegt beim Rechteinhaber.

Protokolltreue bleibt verbindlich

Eigene hDP-Implementierungen müssen sich an die jeweils gültige normative Protokollspezifikation halten.

Herstellerspezifische oder individuelle Erweiterungen dürfen das definierte Protokollverhalten nicht verändern.

Insbesondere dürfen bestehende:

• Endpunkte
• Nachrichten
• Datenstrukturen
• Runtime-Profile
• Pairingverfahren
• Authentifizierungsmechanismen
• Fehlerdefinitionen

nicht eigenmächtig mit abweichender Bedeutung versehen werden.

Neue Protokollfunktionen gelten erst dann als Bestandteil von hDP, wenn sie in die offizielle Spezifikation übernommen wurden.

→ hDP-Protokollspezifikation ansehen

Rechte an eingereichten hDP-Beiträgen

Für Beiträge zum offiziellen hDP-Protokoll, zum offiziellen hDP-Adapter oder zur offiziellen hDP-Firmware gelten besondere Lizenzbedingungen.

Mit dem Einreichen eines entsprechenden Beitrags müssen die erforderlichen Nutzungs- und Lizenzrechte vollständig an den Rechteinhaber übertragen werden, damit die einheitliche Lizenzierung und Weiterentwicklung von hDP erhalten bleibt.

Dies betrifft insbesondere Beiträge zu:

• Protokollspezifikation
• offizieller Firmware
• offiziellem hDP-Adapter
• Referenzimplementierungen
• unmittelbar zu hDP gehörenden Komponenten

Die konkreten rechtlichen Bedingungen werden in der hierfür vorgesehenen Contributor-Vereinbarung festgelegt.

Tests

Vor dem Einreichen eines Pull Requests sollte eine Änderung möglichst in einer realistischen Umgebung getestet werden.

Dabei sollte insbesondere geprüft werden:

• funktioniert die neue Funktion wie vorgesehen?
• funktionieren bestehende Abläufe weiterhin?
• werden Fehlerzustände sauber behandelt?
• funktioniert das Verhalten nach einem Neustart?
• bleiben gespeicherte Einstellungen erhalten?
• entstehen neue Warnungen oder Fehler im Log?

Bei Änderungen an Kommunikationsschnittstellen sollte zusätzlich geprüft werden, ob bestehende Clients oder Adapter weiterhin funktionieren.

Dokumentation gehört zur Änderung

Wenn sich durch eine Änderung:

• Bedienung
• Konfiguration
• API
• Systemverhalten
• Installationsablauf
• unterstützte Funktionalität

ändert, sollte die dazugehörige Dokumentation ebenfalls angepasst werden.

Eine neue Funktion sollte so dokumentiert sein, dass ihre Verwendung ohne Kenntnis des ursprünglichen Entwicklers nachvollziehbar bleibt.

Übersetzungen

Neue sichtbare Texte sollten über das vorhandene Übersetzungssystem eingebunden werden.

Fest im Code hinterlegte Benutzertexte sollten vermieden werden, wenn für den betreffenden Bereich bereits eine Übersetzungsstruktur existiert.

Bestehende Übersetzungen können ebenfalls über Pull Requests verbessert oder ergänzt werden.

Code-Reviews

Pull Requests werden vor einer möglichen Übernahme geprüft.

Dabei können Änderungen verlangt werden, beispielsweise wenn:

• technische Probleme bestehen
• bestehende Funktionen beeinträchtigt werden
• die Umsetzung nicht zur Projektarchitektur passt
• Dokumentation fehlt
• Sicherheitsprobleme bestehen
• vorhandene Strukturen umgangen werden
• eine einfachere oder allgemeinere Lösung möglich ist

Die Übernahme eines Pull Requests ist nicht automatisch garantiert.

Sicherheit

Sicherheitsrelevante Schwachstellen sollten nicht öffentlich als normales Issue veröffentlicht werden, wenn dadurch ein konkreter Angriff erleichtert werden könnte.

Für solche Fälle sollte der dafür vorgesehene private Kontaktweg verwendet werden.

→ Sicherheitsproblem melden

Lizenzierung von Beiträgen

Für Beiträge zum homeESS-Kern gelten die Lizenzbedingungen des homeESS-Projekts.

homeESS steht unter der GNU Affero General Public License v3 (AGPLv3).

Beiträge müssen deshalb mit dieser Lizenz vereinbar sein.

Für eigenständige Adapter gilt dagegen das vom jeweiligen Adapterentwickler gewählte Lizenzmodell.

Für hDP, den offiziellen hDP-Adapter und die offizielle Firmware gelten wiederum eigene Lizenz- und Copyrightbedingungen einschließlich der für Beiträge vorgesehenen Rechteübertragung.

Diese drei Bereiche sind deshalb rechtlich getrennt zu betrachten:

homeESS-Kern
AGPLv3 und Beitragsbedingungen des Open-Source-Projekts.

Eigenständige Adapter
Eigenes Lizenzmodell des jeweiligen Entwicklers, sofern Adapterrichtlinie und API eingehalten werden.

hDP, offizieller hDP-Adapter und offizielle Firmware
Eigenes Copyright und gesonderte Lizenzbedingungen.

Beitragsablauf in Kurzform

Für Beiträge zum homeESS-Kern reicht in der Regel folgender Ablauf:

1. Repository auf GitHub öffnen
2. bei größeren Änderungen zunächst ein Issue erstellen
3. Änderung in einem eigenen Branch oder Fork umsetzen
4. Änderung testen
5. notwendige Dokumentation ergänzen
6. Pull Request erstellen
7. Rückmeldungen aus dem Review einarbeiten

Für eigenständige Adapter gelten zusätzlich die Adapterrichtlinien.

Für Beiträge zu hDP gelten die gesonderten hDP-Beitrags- und Lizenzbedingungen.

→ homeESS auf GitHub
→ GitHub Issues
→ Adapterrichtlinie
→ hDP-Protokollspezifikation