Contribution Guidelines

Allgemeines

Open Source

Die B2B by Practice, sowie unsere Platform, sind Open-Source unter der GNU General Public License.

Um den Open-Source-Gedanken etwas besser leben zu können, ermöglichen wir es im Rahmen der Entwicklung der B2B by Practice, Contributions zu unserem Softwareprodukt beizusteuern. Zur Unterstützung von externen Entwicklungen geben wir Teile unseres Quellcodes frei und ermöglichen den Zugriff auf unser maven-repository (nexus). Für beides muss unsererseits eine IP-Freischaltung durchgeführt werden.

Gleichzeitig bitte auch darauf achten, dass für eine Contribution jeweils immer ein eigenes Ticket über das Jira SD geöffnet werden muss. An diesem kann dann der jeweilige Code der NLI zur Verfügung gestellt werden.

Contribution

Zusätzlich zur dadurch entstehenden Möglichkeit, eigene libraries zu entwickeln und in unsere Auslieferung zu integrieren, bieten wir die Möglichkeit an, externe Entwicklungen in unsere Codebasis zu übernehmen.

Damit eine solche Übernahme des Codes möglich ist, sollten gewisse gemeinsame Coding-Standards eingehalten werden, welche hier in Anhaltspunkten aufgeführt werden.

Guidelines

Richtlinien

Folgende Punkte müssen bei der Einreichung von Contributions erfüllt sein:

• Maven-Modul
  • Es sollte ein vollständiges Maven-Modul geliefert werden.
  • Im Verzeichnis Contributions liegen bereits Maven-Module, welche als Vorlage genutzt werden können.
  • Alternativ kann ein Maven-Modul unter Contributions genannt werden, wo die Sourcen hinzugefügt werden können. Dies macht z.B. Sinn, wenn eine Ergänzung oder Änderung an einer vorherigen Contribution durchgeführt werden soll.
• Formattierung
  • Die Formattierung und das Encoding des Codes müssen stimmen.
• Fehler und Warnungen
  • Der Code darf nicht voll von Warnungen und Sonar-Issues sein!
  • Sollten einzelne Probleme/Issues vorhanden sein, kann dies in Ordnung sein.
• Test
  • Neue Klassen müssen mit einem JUnitTest versehen werden.
  • Dies gilt nicht für ValueObjects (VO), POJOs oder Vergleichbares.
  • Wir nutzen zur Testunterstützung folgende java-frameworks:
    • JUnit 5
    • hamcrest (für asserts)
    • jmockit (in aktueller Version)
    • com.nextlevel.platform:test.util (eigene Erweiterungen und Hilfen in unserer Platform)
  • Der Test sollte aussagekräftig sein und als Vorlage für weitere Tests dienen können.
• keine Duplizierung!
  • Wir nehmen keine Duplikate unserer eigenen Klassen an.
  • Wir nehmen keine minimal veränderten Duplikate unserer Klassen an.
  • Sollte weitere Funktionalität in der bestehenden Logik nötig sein, hilft ein JUnitTest für die neue Funktionalität und die modifizierte Originalklasse. Wir prüfen die Änderungen dann und modifizieren die Originalklasse selbst.
  • DRY
• Klassenstruktur
  • Ein guter Schnitt von Klassen fördert die Lesbarkeit.
  • Bitte keine Klassen/Methoden mit 1.000 Zeilen.
  • Aufteilung nach Funktionalität - Am besten: SRP

Dokumentation

Eine Dokumentation der neuen Funktionalitäten ist sinnvoll! Diese kann durchaus kurz und prägnant ausfallen, es sollte aber erkennbar sein, welche Konfiguration in der B2B by Practice vorgenommen werden muss.

Die Dokumentation kann als Text oder Dokument, im besten Fall direkt markdown-formattiert (diese Dokumentation ist in markdown erstellt) geliefert werden.