Versionierung
Die webbasierten Produkte der AKDB sind auf die Stabilität der Web-Bibliothek angewiesen. Um diese Stabilität auch zur Erhaltung Plattform-weiter Konsistenz und bestmöglicher Bedienbarkeit sicherzustellen, wird das Design System regelmäßig Neuerungen und Verbesserungen bereitstellen. Major Versionen sind verbindlich und von allen webbasierten Produkten der AKDB innerhalb von 3 Monaten zu übernehmen. Neue Releases können sowohl technischer Natur sein (z. B. Code-Anpassungen, Vaadin-Abhängigkeiten) als auch aus Gründen der Bedienbarkeit durch geänderte Mentale Modelle und Stylings erfolgen.
Diese Seite beschreibt die Systematik zur Versionierung des Mate Design Systems. Damit möchten wir gewährleisten, dass alle Nutzer wissen, wie sich die bereitgestellten Ressourcen (Code, Tokens, Design Assets und Anwendungsbeschreibung) vom Launch über die Verfallszeit (deprecation) bis zum Ende ihrer Lebensdauer wandeln.
Das Mate Design System basiert auf "Semantic Versioning" ( SemVer ) und beinhaltet Neuerungen und Weiterentwicklungen auf Basis des folgenden Formats:
broken_image
INFO
* MAJOR Versionen für inkompatible Änderungen (z. B. Style-Änderungen zu Einhaltung der Plattform-weiten Konsistenz oder notwendige API-Anpassungen)
* MINOR Versionen für rückwärts-kompatible Erweiterungen wie z. B. eine neue UI-Komponente
* PATCH Versionen beheben Fehler und optimieren vorhandene Funktionen, ohne die Kompatibilität zu brechen. (z. B. Refactoring von Code ohne Beeinträchtigung der Funktionalität)
broken_image
Inkrementelle Versionierung
Jegliche Änderungen werden als eine, gebündelte neue Version freigegeben: Neuerungen / Änderungen im Design System (API, Style, Icons, Fonts, Dokumentation) werden als eine Gesamtversion zur Verfügung gestellt. Das heißt, dass dieselbe Versionsnummer gleichzeitig auf alle System-Assets angewendet wird. Eine Design System Version ist ein Bundle diverser Komponenten-Versionen und kann erst veröffentlicht werden, wenn alle Komponenten zusammenpassen. Die Design System Version stellt den Master dar.
Eine neue Version (ob Major oder Minor) gilt für alle Komponenten. Dadurch können Abhängigkeiten besser integriert werden und die "Handhabe" für die Nutzer wird vereinfacht. Sobald ein versioniertes Paket released wurde, darf der Inhalt dieser Version nicht mehr geändert werden. Jegliche Änderungen / Neuerungen können im Changelog eingesehen werden.
Ein Release: Beinhaltet neben Anpassungen der Dokumentation (z. B. einer Verhaltensbeschreibung einer Komponente) meist auch einen technischen Teil (Code Snippets).
Kein Release: Ist der redaktionelle UX-Teil (ohne Code) stabil, kann dieser bereits von allen Anwendern des Systems eingesehen und für die Implementierung herangezogen werden. In diesem Fall handelt es sich nicht um ein Release.
Major
Sogenannte "Breaking Changes" (inkompatible Änderungen) sind für alle Anwender mit Aufwand verbunden, weshalb wir uns bemühen, die Anzahl der Änderungen auf das Notwendigste zu begrenzen. Zudem werden wir maximal zwei Major-Änderung pro Jahr veröffentlichen. Die Adaption von Major-Versionen ist obligatorisch und gilt für alle Organe der AKDB. Jedes entwickelnde Organ der AKDB verpflichtet sich zur Integration / Migration des Major-Release innerhalb von 3 Monaten nach Release. Die Frist endet 3 Monate nach dem Veröffentlichungstag. Im Rahmen von Quality Gates werden wir u. a. den Code von Implementieren prüfen um die Verwendung der AKDB-Komponenten-Bibliothek sicherzustellen. Dadurch kann eine effiziente Bedienbarkeit über alle Produkte der AKDB gewährleistet und Redundanzen in der Produktentwicklung vermieden werden. Auch ohne "Breaking Changes" auf technischer Basis kann es zu Major Versionen kommen, um die Usability oder die Plattform-weite Konsistenz nachhaltig zu gewährleisten. Mit Major Versionen können wir unseren Kunden eine gute und konsistente Bedienbarkeit innerhalb der Mate-Plattform bieten und gesetzlichen Anforderungen zur Einhaltung der Barrierefreiheit nachkommen. Major Releases erfolgen bis zu 2 Mal im Jahr.
Beispiele:
- Usability: Eine vorhandene Komponente wird durch eine Komponente ersetzt, welche die Bedienbarkeit / Benutzerfreundlichkeit erheblich verbessert (z. B. "Toast" ersetzt "Modaler Dialog")
- Style: Wesentliche Änderungen von Design Tokens
- API: Entfernen oder Umbenennung von Properties, öffentlichen Methoden, benutzerdefinierten Events oder Slots
- Dependency: Eine neue Vaadin-Version, die genutzt werden muss.
Minor
Additive Änderungen / Neuerungen mit voller Rückwärtskompatibilität aller Funktionen. Neu- und Weiterentwicklungsprojekte sollten auf Basis des aktuellen Minor Release arbeiten. Anpassungen bestehender Programmteile durch die entwickelnden Organe der AKDB sind nicht verbindlich. Minor Releases erfolgen ca. alle 2 Monate.
Beispiele:
- API & Code: Bei neuen Properties, öffentlichen Methoden
- Style: Bei mehrschichtigen Komponenten wie z. B. Popovers, die sich nicht auf die darunterliegende Seite auswirkt.
- Icon: Ein neues Icon steht zur Verfügung
Patch
Beheben Fehler und optimieren vorhandenen Code. Patches erfolgen je nach Bedarf alle 2-6 Wochen.
Beispiele:
- Ausbesserung von Styling-Problemen die zu einer besseren Lesbarkeit oder Darstellung führen.
- Ausbesserung der Komponentendokumentation
Deprecation & Ending Life
Die Kennzeichnung von Komponenten und Muster mit dem Hinweis "Deprecated" (zu Deutsch: "veraltet") warnt die Anwender davor, dass die Nutzung des Features eingestellt wird und der Support in Zukunft ausläuft. Das System bietet dann eine bevorzugte Alternative. Die Kennzeichnung von veralteten Lösungen kann via Major, Minor oder Patch Versionen veröffentlicht und kommuniziert werden.
- Deprecated Kennzeichnung mit einem Major Release: Es gelten die Integrations- / Migrationsfristen für Major Releases (3 Monatsfrist).
- Deprecated Kennzeichnung mit einem Minor- und / oder Patch-Release: Unterliegt zunächst (bis zum Major Release) keiner zeitlichen Frist zur Integration / Migration.
Für alle Release-Arten (Major, Minor, Patch) gilt: Die als "Deprecated" gekennzeichnete, d. h. veraltete Lösung darf nicht mehr für Neuentwicklungen verwendet werden. Aus diesem Grund ist die Deprectated Kennzeichnung sinnvoll um Fehlentwicklungen zu vermeiden, auch wenn es noch kein verbindliches Major-Release gibt. Der Vorteil des Deprecated-Prinzips für die Fachbereiche besteht aufgrund der frühzeitigen Kommunikation alternativer, verbesserter Lösungen bereits in der Vorversion: Die Fachbereiche können die neue Lösung bereits vor Release einer Major-Version integrieren und die Integrations-/Migrationsfrist kann dadurch "entschäft" werden.
Wie sieht so eine Kennzeichnung konkret aus? Ein Beispiel anhand einer Komponente: Bevor eine Komponente durch eine verbesserte Lösung via Major-Release (3.0.0) gänzlich ersetzt wird, werden die Anwender innerhalb eines vorherigen Releases (z. B. 2.1.0) mit Hinweis auf den zeitlichen Horizont der verbindlichen Umstellung informiert. Bis zur Erscheinung des Major-Release (3.0.0) bietet das Design System beide Varianten an: Die verbesserte Komponente auf der Default-Seite und die veraltete Lösung auf einer separaten Seite. Beide Seiten verlinken sich gegenseitig innerhalb einer Hinweis-Meldung am Seitenanfang. Die u. g. Abbildung demonstriert eine solche Hinweis-Meldung.
Contribution
Wenn Sie der Meinung sind, Ihre fachlichen Anforderungen nicht mit den im Design System dokumentierten Lösungen adressieren zu können bzw. Verbesserungen und Neuerungen im Design System einbringen wollen, befolgen Sie bitte den Prozess zur Contribution.
Kommunikation
Das Mate Design System Team informiert die Product Owner innerhalb der gemeinsamen, regelmäßigen Sync-Termine (PO-Team-Meeting und Tech-Sync) über bevorstehende und neue Veröffentlichungen sowie Deprecation / Ending Life Fristen.
Dependencies
Für einige Mate-Basiskomponenten werden Mindesversionen (z. B. Vaadin- oder QSYSneo-Deliveries, Design Tokens etc.) vorausgesetzt. Komponenten die keine Mindestversion angeben, sind mit jeder API-Version verwendbar. Die Mindestversionen werden im Design System dokumentiert. Alle Artefakte und Ressourcen werden ausschließlich aus dem Nexus gezogen. Im Falle, dass der Nexus nicht die gewünschte Komponente liefert, kann über das QSYSneo-Team ( team-vaadin@akdb.de ) die Ressource nach einer Prüfung ins Nexus übernommen werden.
Dependency-Änderungen (z. B. neue Vaadin-Versionen) müssen nicht zwingend ein Update des Design Systems nach sich ziehen.
Support-Richtlinie
Wir unterstützen nur die neueste Major-Version des Design Systems und nehmen keine Änderungen an älteren Versionen vor.