Versionierung & Build

Unabhängige Versionierung

Lino-Projekte können mehrere Services und Webanwendungen enthalten. Jedes bereitstellbare Element besitzt eine eigene Version, sodass eine kleine Korrektur in einem Service keinen künstlichen Release des gesamten Systems erzwingt. Das ist wichtig in modularen und verteilten Architekturen, in denen APIs, Worker, Web Apps, Migrations und Integrationsverträge sich in unterschiedlichem Tempo weiterentwickeln können.

Die operative Version wird in einer einfachen Textdatei namens version.txt gespeichert. Für Services liegt die Datei unter src/Services/<ServiceName>/version.txt. Für Webanwendungen liegt sie unter src/WebApps/<WebAppName>/version.txt. Die Lino CLI liest diese Dateien beim Auflisten, Anzeigen, Erhöhen und Erzeugen versionierter Builds.

Von Lino verwendete SemVer-Regel

MAJOR.MINOR.PATCH

• PATCH erhöht die letzte Zahl und sollte für kompatible Korrekturen, kleine interne Verbesserungen und Änderungen verwendet werden, die den öffentlichen Vertrag nicht verändern.
• MINOR erhöht die mittlere Zahl und setzt patch auf null zurück. Verwenden Sie dies für rückwärtskompatible Funktionen, neue Endpoints, optionale Felder oder additives Verhalten.
• MAJOR erhöht die erste Zahl und setzt minor und patch auf null zurück. Verwenden Sie dies, wenn Verbraucher sich anpassen müssen, zum Beispiel weil sich ein API-Vertrag inkompatibel geändert hat oder ein Verhalten bewusst ersetzt wurde.

Beispiele: 1.0.0 kann die erste stabile Version darstellen, 1.0.1 eine kompatible Korrektur, 1.1.0 eine neue kompatible Fähigkeit oder neue Endpoints ohne Breaking Change und 2.0.0 einen Release mit Änderungen, die eine Aktualisierung der Clients erfordern.

Aktuelle Versionen anzeigen

Verwenden Sie lino version list, um die aktuellen Versionen aller Services und Webanwendungen des Projekts zu sehen:

lino version list

Verwenden Sie lino version show, wenn Sie die Version eines bestimmten Service oder einer bestimmten Webanwendung anzeigen müssen. Der Befehl fragt, ob das Ziel ein Service oder eine Webanwendung ist, und zeigt die Version aus der entsprechenden version.txt-Datei an.

lino version show

Eine Version erhöhen

Verwenden Sie lino version bump, wenn ein Service oder eine Webanwendung bereit für einen neuen Release ist:

lino version bump

1. Führen Sie den Befehl aus dem Projektstamm aus.
2. Wählen Sie einen oder mehrere Services oder Webanwendungen aus. Der Prompt zeigt jedes Element mit seiner aktuellen Version.
3. Wählen Sie den Erhöhungstyp: patch, minor oder major.
4. Bestätigen Sie die Antworten. Lino aktualisiert die ausgewählten version.txt-Dateien und zeigt eine Tabelle mit den neuen Versionen an.

Jede Ausführung sorgt für eine klare Änderungsverfolgung, verbessert die Konsistenz mit Release-Praktiken und erleichtert die Abstimmung mit CI/CD-Pipelines. Die Versionsnummer ist damit kein loses Detail mehr, sondern identifiziert das bereitstellbare Artefakt, das sich tatsächlich geändert hat.

Versionsänderungen sollten zusammen mit den technischen Auswirkungen des Releases geprüft werden. Eine Datenbank-Migration kann an die Version eines Service gebunden sein, API-Verbraucher benötigen möglicherweise Vertragsnotizen und Integrationsereignisse können Kompatibilitätsprüfungen erfordern. Wenn die Version nahe am bereitstellbaren Element bleibt, werden diese Entscheidungen explizit und leichter auditierbar.

Prüfen Sie vor einer major-Erhöhung öffentliche APIs, Ereignisverträge, Migrations, Client-Kompatibilität und externe Verbraucher. Vor einer minor-Erhöhung bestätigen Sie, dass das neue Verhalten additiv ist. Vor einem patch bestätigen Sie, dass die Änderung kompatibel ist und keine Nutzungserwartungen verändert.

Build und Containerisierung

In den Videos und in der täglichen Entwicklung wird dotnet build häufig verwendet, um zu prüfen, ob die generierte Lösung nach jedem Modellierungsschritt weiterhin kompiliert. Der Befehl lino build hat ein anderes Ziel: ausgewählte Services und Webanwendungen für einen Release vorzubereiten, indem sie im Release-Modus mit dem .NET-Container-Veröffentlichungsprofil veröffentlicht werden.

Diese Trennung verhindert, dass eine einfache Kompilierungsprüfung als Lieferpaket behandelt wird. Verwenden Sie dotnet build während der Entwicklung, um Fehler früh zu finden. Verwenden Sie lino build, wenn das Artefakt bereit ist, eine Version zu erhalten, zu einem Container-Image zu werden und in einen Registry oder eine Deployment-Pipeline zu gehen.

Was lino build tut

Führen Sie den Befehl aus dem Stamm eines Lino-Projekts aus:

lino build

Die CLI validiert den authentifizierten Benutzer und die aktuelle Projektkonfiguration, fragt, welche Services oder Webanwendungen in den Build aufgenommen werden sollen, und fragt anschließend, ob die Version beibehalten oder erhöht werden soll. Wenn eine Erhöhung ausgewählt wird, aktualisiert Lino die entsprechende version.txt, bevor die Build-Befehle erzeugt werden.

Das Backend gibt die exakt auszuführenden Befehle zurück. Aktuell verwenden diese Befehle dotnet publish mit -c Release, -p:PublishProfile=DefaultContainer, -p:ContainerRepository, -p:ContainerImageTag und -p:ContainerLabelVersion. Das Image-Tag und das Versionslabel des Containers erhalten denselben SemVer-Wert, der für den Release gewählt wurde.

Praktisch kompiliert der Prozess den Code des Service oder der Webanwendung, wendet die notwendige Veröffentlichungskonfiguration an, erzeugt ein Container-Image auf Basis der aktuellen SemVer-Version und weist dem Artefakt standardisierte Namen, Tags und Metadaten zu.

Generierte Repository-Namen

Lino normalisiert Projekt- und Elementnamen, um vorhersehbare Container-Repositories zu erzeugen:

• Einfache Service-API: <project-name>/services/<service-name>-api:1.2.3
• Modularer Service-Host: <project-name>/services/<service-name>-host:1.2.3
• Blazor-Webanwendung: <project-name>/webapps/<webapp-name>:1.2.3

Diese Konvention hält Service-APIs, modulare Hosts und Webanwendungen im Registry getrennt und bewahrt die Release-Version im Tag. Das Muster beseitigt außerdem wiederholte manuelle Entscheidungen und reduziert Abweichungen zwischen Umgebungen, CI/CD-Skripten und operativer Dokumentation.

Veröffentlichung in Registries

Die erzeugten Images können im Registry veröffentlicht werden, den Ihre Deploy-Plattform verwendet:

• Docker Hub
• GitHub Container Registry
• AWS ECR
• Azure Container Registry
• jeder andere OCI-kompatible Registry.

Verwenden Sie beim Deploy nach Möglichkeit unveränderliche Versions-Tags wie 1.2.3 statt fließender Tags. Das verbessert Rollback, Auditierbarkeit und den Vergleich zwischen dem, was gebaut, veröffentlicht und bereitgestellt wurde.

Empfohlener Release-Ablauf

1. Führen Sie die Projekttests und dotnet build aus, um den Quellcode vor dem Paketieren zu validieren.
2. Prüfen Sie die aktuellen Versionen mit lino version list und bewerten Sie, welche Services oder Webanwendungen sich geändert haben.
3. Verwenden Sie lino build und wählen Sie, ob die aktuelle Version beibehalten wird oder eine patch-, minor- oder major-Erhöhung erhält.
4. Veröffentlichen Sie die erzeugten Container-Images im Registry der Deployment-Plattform, etwa Docker Hub, GitHub Container Registry, AWS ECR, Azure Container Registry oder einem anderen kompatiblen Registry.
5. Stellen Sie mit nachvollziehbaren Versions-Tags bereit und halten Sie Changelog, Migrations und Rollback-Plan mit demselben Release verbunden.

Legen Sie keine Secrets, Produktions-Connection-Strings oder umgebungsspezifischen Zugangsdaten in den erzeugten Images ab. Verwenden Sie Umgebungsvariablen, user secrets für lokale Entwicklung, Secret-Stores des CI/CD oder den Secret-Mechanismus der Deploy-Plattform.

Mit diesem Ablauf bleiben Versionierung und Build verbunden: derselbe im Projekt gespeicherte SemVer-Wert wird als Container-Tag und als Release-Metadatum verwendet, was die Nachverfolgbarkeit zwischen Quellcode, Migrations, API-Verträgen, Integrationsereignissen und bereitgestellten Artefakten verbessert.