Contributing Guidelines

Wir freuen uns sehr über Ihr Interesse, sich am Projekt F13 zu beteiligen. Wir begrüßen jede Form der Unterstützung, seien es Codevorschläge, Fehlermeldungen, Dokumentationsverbesserungen oder Feedback.

Wir erwarten von allen Teilnehmerinnen und Teilnehmern respektvolles Verhalten. Unsere Community soll inklusiv und einladend sein. Belästigung, Diskriminierung oder respektloses Verhalten werden nicht toleriert. Für weitere Details, beachten Sie bitte den F13 Code of Conduct. Wir verweisen außerdem auf die Coding und Security Grundsätze von openCoDE.

Wie kann ich beitragen?

Es gibt viele Möglichkeiten, wie Sie zum Projekt beitragen können:

Haben Sie Feature Requests oder einen Bug gefunden oder wollen generell Code ins F13-Projekt einfließen sehen? Erstellen Sie ein Issue im jeweiligen Repository und idealerweise direkt einen Merge Request.
Haben Sie Fragen oder benötigen Unterstützung, können Sie sich an das Entwicklungsteam wenden.

Vielen Dank für Ihre Unterstützung!

Sie haben weitere Fragen zu den Contributing Guidelines?

Nutzen Sie die verschiedenen Austauschmöglichkeiten unter Kontakt.

Verbessungswünsche, Fehler oder Featureanfragen

In Kürze

Um Issues, beispielsweise generelles Feedback, Featureanfragen oder Fehler zu melden, können Sie die bereitgestellten Issue-Vorlagen verwenden. Erstellen Sie ein neues Issue und benutzen sie eine der vorhandenen Vorlagen.
Beachten Sie die Anweisungen in der Vorlage und füllen Sie alle erforderlichen Felder aus.
Haben Sie konkrete Verbesserungsvorschläge zum Code, sei es ein ein neues Feature oder eine Fehlerbehebung, können Sie aus dem Issue direkt einen Merge Request erstellen.

Für die Organisation der operativen Zusammenarbeit ist die Nutzung der GitLab-Instanz bei Open Code zentral, wobei insbesondere den Issues eine zentrale Bedeutung zukommt. Tickets („Issues“) übersetzen übergreifende Entwicklungsziele und Meilensteine in konkrete, auf die unmittelbare Entwicklungsarbeit bezogene Aufgabenbeschreibungen. Die Definition und Verteilung der Issues liegt im Aufgabenbereich der jeweils zuständigen Microservice-Leads (MSL; für Details siehe Rollen und Verantwortlichkeiten). Die Übersicht über geplante, aktuelle und abgeschlossene Issue wird über Issue-Boards abgebildet, die sich eng an der Kanban-Methode orientieren. Inhaltliche Abstimmungen zu Bearbeitungsständen erfolgen sowohl asynchron über Kommentierungen der Issues als auch synchron im Rahmen regelmäßiger Check-ins in Form von Stand-ups, Weeklies oder weiterer Formate zwischen den Entwicklerinnen und Entwickler und MSLs.

Entwicklung und Integration von Code-Beiträgen

In Kürze

Eröffnen Sie zunächst ein Issue ("Ticket") zur Diskussion größerer Änderungen. Issues haben Vorlagen, die sie benutzen können.
Erstellen Sie einen Merge Request von Ihrem Branch in den main-Branch.
Halten Sie Ihren Branch aktuell mit dem main-Branch.
Fügen Sie Tests für neue Funktionalitäten hinzu.
Stellen Sie sicher, dass alle Tests erfolgreich durchlaufen.
Aktualisieren Sie die Dokumentation bei Bedarf.
Sobald der Merge Request bereit ist, kommentieren Sie ihn und bitten Sie um eine Überprüfung durch ein Mitglied des Entwicklungsteams. Wenn Sie Hilfe und Unterstützung brauchen, merken Sie dies direkt an.
main-Branches sind geschützt und können nur vom Entwicklungsteam durch einen Merge Request aktualisiert werden, sie können also auch nichts "kaputt" machen.

Der dezentrale, gemeinschaftsbasierte Entwicklungsansatz erfordert die fundierte Überprüfung der Code-Qualität sowie Einhaltung der wechselseitig anerkannten Standards. Die positive Überprüfung ist die zentrale Voraussetzung für die Übernahme und Zusammenführung von Entwicklungsbeiträgen. Innerhalb der Microservices verläuft der idealtypische Integrationsprozess wie folgt:

Auf Basis der durch MSLs definierten Issues können Entwicklerinnen und Entwickler über Merge Requests neue Branches erstellen und diese im Sinne der Issues bearbeiten. Die Weiterentwicklungen oder Änderungen des Codes im neuen Branch werden durch Commits festgehalten. Ein Commit ist wie ein Schnappschuss des Branches zu einem bestimmten Zeitpunkt und enthält eine Beschreibung der durchgeführten Änderungen.
Wenn die Arbeit am Branch aus Sicht des oder der Entwickelnden abgeschlossen ist, wird der Commit unter Verweis auf die adressierten Issues in das entsprechende Repository gepusht, damit andere Teammitglieder die Änderungen sehen können.
Die MSLs koordinieren infolge die Code Reviews für die Commits. Insbesondere in der Anfangsphase werden das EntwicklerInnen-Team der PD sowie gegebenenfalls weitere professionelle Entwicklungsdienstleister den Großteil der Review-Aufgaben übernehmen. Sofern sich Überarbeitungs- oder Klärungsbedarfe ergeben, werden Review-Sessions mit allen beteiligten Akteuren organisiert. Nach der Überprüfung und Genehmigung wird der Commit in dem Hauptbranch zusammengeführt („Merge“).

Testing und Release-Veröffentlichung

In Kürze

Schreiben Sie Tests für neue Funktionalitäten.
Stellen Sie sicher, dass alle Tests positiv durchgelaufen sind, bevor Sie einen Merge Request erstellen.
Automatisierte Tests werden bei jedem Merge Request ausgeführt.
Ohne ein komplettes Durchlaufen der GitLab-Testpipeline sowie der Code-Qualitäts-Stages kann ein Merge Request nicht durchlaufen.

Im Kontext der modularen Weiterentwicklung von F13 stellen einheitliche Qualitätskontrollen und Tests der neuen bzw. weiterentwickelten Module / Microservices eine wichtige Voraussetzung dar, um die Kompatibilität und Verlässlichkeit neuer Releases zu gewährleisten. Im Kontext der F13 Community übernimmt das Core Development Team (CDT; für Details siehe Rollen und Verantwortlichkeiten) die Hauptverantwortung für diesen Entwicklungsschritt, so dass das F13-CO hier nur bedarfsweise Unterstützung liefert. Ganz generell sollte das Testing jedoch verschiedene Aspekte abdecken:

Unit-Tests: Entwicklerinnen und Entwickler schreiben und führen Unit-Tests durch, um sicherzustellen, dass einzelne Code-Einheiten oder ganze Module wie erwartet funktionieren
Integrations- und Systemtests gewährleisten die Einhaltung der allgemeinen Guidelines dahingehend, dass einzelne Microservices zueinander und zur Gesamtarchitektur von F13 passen.
Compliance-Checks stellen sicher, dass die Bedingungen der gewählten Open Source-Lizenz und allgemeine Anforderungen an Datensicherheit adäquat berücksichtigt wurden. Im Fall der Lizenzprüfung eingereichter Beiträge steht der von PD eigesetzte Lizenzprüfer allen Entwicklerinnen und Entwickler als Self-Service-Tool zur Verfügung. Die finale Abnahme wird im Rahmen der Compliance Checks jedoch durch das CDT verantwortet. Ergänzend sollten - wo immer möglich - auch Nutzerinnen- und Nutzertests durchgeführt werden, um Feedback von echten Nutzern zu erhalten.

Sofern Release-Kandidaten entlang der Tests positiv begutachtet sind, werden sie in eine stabile Version der Software auf openCoDE überführt. Die Veröffentlichung der neuen Pakete / Versionen und Release Notes findet in den jeweiligen Repositories statt. Das F13-CO stellt die ergänzende Öffentlichkeitsarbeit sowie die Kommunikation in die relevanten Stakeholderebenen sicher.

Release-Planung und Changelog

Aktuell ist vorgesehen, jeweils am letzten Donnerstag im Monat eine neue Version aller Microservice-Container bereitzustellen - jedoch nur, wenn im Vormonat Änderungen an den jeweiligen Services vorgenommen wurden. Dazu werden alle bis zu einer Woche vor dem letzten Donnerstag fertig bearbeiteten Issues in die neuen Container-Versionen mit einbezogen.

Wir gehen nach folgendem Bezeichnungsschema vor:

vX.Y.Z mit X als Major-, Y als Minor- sowie Z als Patch-Version.

Major-Versionsbezeichnungen beinhalten Breaking Changes, API-Redesigns, Änderungen der Architektur oder die Entfernung von als deprecated eingestuften Features. Minor-Versionsbezeichnungen sind neue Features, neue Endpoints, Verbesserungen oder API-Erweiterungen, die eine Rückwärtskompatibilität beinhalten. Patch-Versionsbezeichnungen entstehen durch Bug- oder Security-Updates, kleinere Anpassungen oder Performance-Verbesserungen.

1.0.0 ist der initiale Release der F13-Container auf openCoDE.

Jeder Microservice enthält ein Changelog.md, in dem die veröffentlichten und noch nicht veröffentlichten Anpassungen in sprechender Form mit Verweis auf die jeweiligen Tickets beschrieben sind.

Ein Beispiel-Changelog ist folgendes:

[Unreleased] -- Wird kontinuierlich befüllt

Added

* Neues Feature (#Issue)

Changed

* Anpassung A (#Issue)

Deprecated

* Deprecated Feature (#Issue)

Removed

* Entfernung von B (#Issue)

Fixed

* Fehler C korrigiert (#Issue)

Security

* Sicherheitsanpassung D (#Issue)


[1.0.0] - 2025-07-24
Initiales OpenCode - Release

Das Changelog wird entweder von der das Ticket bearbeitenden Person, der den Merge Request reviewenden Person oder spätestens in der Abnahme durch den Product Owner bearbeitet und erweitert.

Das Vorgehen bei Releases ist wie folgt:

Der main-Branch enthält immer den aktuellen Entwicklungsstand.
Aus dem main-Branch wird eine Woche vor dem letzten Donnerstag ein release-Branch gezogen. Dieser wird getestet.
Zum Releasetag wird, wenn die Tests erfolgreich waren und die Abnahme erfolgt ist, ein Git-Tag aus dem release-Branch gezogen.
Zusätzlich zum Git-Tag wird ein Container mit der gleichen Versionsnummer wie der Tag erstellt und ein GitLab-Release, in dem die Release-Notes und bekannte Einschränkungen und Fehler enthalten sind, erstellt.

Entwicklungsumgebung

Zum Aufsetzen der Entwicklungsumgebung beachten Sie bitte die Anweisungen in der README-Datei des jeweiligen Repositories. Hier finden Sie alle notwendigen Informationen zur Einrichtung der Umgebung und zum Starten der Anwendung.

Coding Standards

Halten Sie sich an bestehende Code-Formatierung und Namenskonventionen.
Schreiben Sie sauberen, lesbaren und wartbaren Code.
Kommentieren Sie komplexe Funktionalitäten.
Entwicklungssprache, inklusive Kommentaren und Doc-Strings, im Code ist Englisch
Python-Code ist am Google Python Style Guide (externer Link) ausgerichtet. Allerdings wird nicht Pylint sondern Ruff (externer Link) für Linting und Formatierung verwendet.
In den Python-basierten Microservices Core, Chat, RAG, Parser und Zusammenfassung werden pre-commit-Hooks (externer Link) für Python benutzt, die ein Linting und eine Formattierung mittels Ruff sicherstellen. Dieser pre-commit-Hook kann mit der passenden Konfigurationsdatei, in allen Microservices .pre-commit-config.yaml genannt, lokal eingerichtet werden. Damit wird vor einem Commit eine saubere Formatierung und ein Python-Linting sichergestellt. Zusätzlich wird auch nach jedem Push oder Merge ins Repository, ob auf Feature- oder main-Branch die pre-commit-Anforderungen an Code-Qualität und Formattierung einer GitLab-Pipeline automatisch geprüft.
Der Frontend-Microservice verwendet Biome (externer Link) für Linting und Formatierung und ist im Microservice ebenfalls in einem pre-commit-Hook sowie in einer GitLab-Pipeline definiert und integriert.

Commit Messages

In Commit Messages sollte ein einheitlicher Stil eingehalten werden. Commit Message-Sprache ist entweder Deutsch oder Englisch. Commit Messages sollten knapp gehalten werden und trotzdem auf den ersten Blick zeigen, was in diesem Commit passiert ist. Eine sinnvolle Kurznotation ist:

Kürzel	Beschreibung
ADD [feature X]	Added file (Datei hinzugefügt)
RM [feature Y]	Removed file (Datei entfernt)
BF [feature Z]	Bugfix (Fehlerbehebung)
NF [feature A]	New feature (Neues Feature)
DOC [feature B]	Documentation added or changed (Dokumentation angepasst oder hinzugefügt)
RF [feature C]	Refactoring (Überarbeitung)

Eine mögliche Commit Message wäre beispielsweise ADD [imagegen]: Dockerfile für Bildgenerierung hinzugefügt.

Dokumentation

Dokumentieren Sie neue Funktionen (mit Docstrings) oder APIs (mit Code-Kommentaren).
Halten Sie die README-Datei und andere Dokumentation aktuell.

Kommunikation

Bei Fragen können Sie ein Issue eröffnen.
Für schnellere Hilfe wird perspektivisch ein dedizierter Chat-Kanal erstellt (Updates folgen)

Lizenz

Durch das Einreichen von Beiträgen akzeptieren Sie, dass Ihre Arbeit unter der im Projekt verwendeten Lizenz (MPL-2.0) veröffentlicht wird.