README geschrieben

README.md

@@ -1,3 +1,173 @@
 # release action
 
-TODO document usage
+Gitea/Github-Action, die hilft das Veröffentlichen von Projekten zu automatisieren.
+
+## Features
+  - Laden von Credentials und Einrichten der Runner-Umgebung
+  - Veröffentlichen von Artefakten
+    - Docker Images
+    - Python Pakete (wheel, sdist)
+    - NPM Pakete
+    - Tarballs
+  - Ausrollen von Helm-Releases
+  - Anlegen von Gitea-Releases
+  - Anlegen von Git-Tags
+
+## Verwendung
+Die Action erwartet eine Beschreibung des zu veröffentlichenden Projekts in `.gitea/release.yaml`.
+Darin werden folgende Eigenschaften beschrieben:
+ - Welche Datei legt die aktuelle Version fest?
+ - Welche Artefakte sollen veröffentlicht werden?
+ - Welche Releases sollen wann aktualisiert werden?
+
+### Beispiel für release.yaml
+```#!yaml
+# Die Version wird in der Datei Cargo.toml im Hauptverzeichnis des Projekts festgelegt
+version_descriptor: Cargo.toml
+
+artefacts:
+  # Es soll ein Docker/OCI-Image mit dem Namen masa-images veröffentlicht werden
+  - type: oci_image
+    name: masa-images
+
+  # Es soll ein Python-Paket als Wheel veröffentlicht werden 
+  - type: wheel
+    # Unter diesem Pfad ist das Wheel abgelegt (vor dem Upload in die Registry)
+    filename: ./scratch/wheels/*.whl
+    # Diese Datei bestimmt die Version des Pakets.
+    # Wird synchronisiert mit der Version des Projekts.
+    version_descriptor: pyproject.toml
+
+deployments:
+  # Bei einem Prerelease (push in testing) soll das Helm-Release masa-images-testing
+  # aktualisiert werden.
+  - type: helm
+    release_name: masa-images-testing
+```
+
+Alle möglichen Einstellungen können [hier](https://gitea.puzzleyou.net/actions/release/src/branch/master/src/release/tests/assets/release.yaml) eingesehen werden.
+
+### Aufruf im Workflow
+Die Action kann die generischen Aufgaben bei einem Release übernehmen. Was sie nicht kann
+ist die Artefakte bauen. Wie das zu tun ist muss das Projekt selbst beschreiben.
+
+Dafür gibt es zwei Möglichkeiten: Die Kurzform in einem Schritt und die Langform in mehreren Schritten.
+
+#### Langform
+Wenn ein Projekt veröffentlicht wird, dann werden folgende Schritt ausgeführt:
+- `actions/release/declare`: Hier wird die `release.yaml` gelesen und die Credentials werden geladen.
+- `actions/release/sync-versions`: Hier werden die Versionen der Artefakte mit der Version des Projekts synchronisiert.
+- Hier muss das Projekt die Artefakte bauen.
+- `actions/release/release`: Hier werden die Artefakte veröffentlicht, das Helm-Release aktualisiert und das Gitea-Release angelegt.
+
+Beispiel:
+```#!yaml
+name: release
+on:
+  push:
+    branches:
+      - master
+      - testing
+
+jobs:
+  check:
+    uses: ./.gitea/workflows/checks.yaml
+
+  release:
+    needs: ["check"]
+    runs-on: action-runner
+    env:
+      RUSTC_WRAPPER: sccache
+    steps:
+      - uses: actions/checkout@v4
+      - uses: https://gitea.puzzleyou.net/actions/release/declare@v0
+      - uses: https://gitea.puzzleyou.net/actions/release/sync-versions@v0
+
+      - name: build image
+        run: |
+          nix develop --command just build-image ${RELEASE_IMAGE_TAG}
+          sccache --show-stats
+
+      - name: build wheel
+        run: |
+          mkdir -p ./scratch/wheels
+          nix develop --command \
+            maturin build \
+              --release \
+              --out ./scratch/wheels/ \
+              --strip \
+              -m Cargo.toml \
+              --compatibility linux \
+              --interpreter python3.13
+          sccache --show-stats
+
+      - uses: https://gitea.puzzleyou.net/actions/release@v0
+```
+
+#### Kurzform
+Wenn es nur ein Artefakt gibt und das auch einfach zu bauen ist, dann kann die Kurzform `actions/release` verwendet werden. Das ist der Normalfall.
+Im Parameter `build_run` muss das Projekt (in Form eines Bash-Scripts) beschreiben wie die Artefakte gebaut werden.
+
+Beispiel:
+```#!yaml
+name: release
+on:
+  push:
+    branches:
+      - master
+      - testing
+
+jobs:
+  release:
+    runs-on: action-runner
+    steps:
+      - uses: actions/checkout@v4
+      - uses: https://gitea.puzzleyou.net/actions/release@v0
+        with:
+          build_run: docker build -t "${RELEASE_IMAGE_LOCAL_NAME_ALI}" .
+```
+
+## Umgebungsvariablen
+Die Action stellt einige Umgebungsvariablen bereit, die im Workflow nützlich sein können:
+- `RELEASE_IMAGE_TAG`: Tag, der Docker/OCI-Images zugewiesen werden muss, damit diese veröffentlicht und in Helm-Releases verwendet werden können. Entspricht momentan dem Commit-Hash.
+- `RELEASE_IMAGE_LOCAL_NAME_XXX`: Voller Name eines Docker/OCI-Images mit Tag.
+- `RELEASE_IS_PRERELEASE`: Wird gerade ein Release (master/main) oder ein Prerelease (testing) verarbeitet?
+- `RELEASE_PROJECT_IS_RELEASED`: Wurde das Projekt schon unter dieser Version veröffentlicht?
+- `RELEASE_PROJECT_CURRENT_VERSION`: Aktuelle Version des Projekts, z.B. '2.10.4'
+- `RELEASE_PROJECT_PLANNED_VERSION`: "Geplante" Version des Projekts. Entspricht der aktuellen Version mit optionalem Suffix bei Prerelease, z.B. '2.10.4-dev42'
+
+## Release vs. Prerelease
+Die Release-Action kann für Releases (merge in master/main) oder Prereleases (merge in testing) verwendet werden.
+
+Es unterscheiden sich dann image-tags, git-tags und Versionsnummern der Artefakte.
+
+### Release
+- Image-Tags: `v1`, `v1.2`, `v1.2.3`, `latest`, `master/main.latest`
+- Git-Tags: `v1`, `v1.2`, `v1.2.3`, `latest`
+- Versionsummern: Wie Projekt
+
+### Prerelease
+- Image-Tags: `v1.2.3-dev4`, `development`, `testing.latest`
+- Git-Tags: `v1.2.3-dev4`, `development`
+- Versionsnummern: Wie Projekt, mit Suffix `-dev$ACTION_LAUF_NUMMER`
+
+## Prüfung ob eine Version schon veröffentlicht wurde
+Beim Release selbst (merge in main/master) wird geprüft ob eine Version bereits veröffentlicht wurde.
+Falls ja, ist das kein Fehler. **ABER** es wird in dem Fall weder ein Docker/OCI-Image hochgeladen, noch ein Helm-Release aktualisiert oder irgendwelche anderen Artefakte veröffentlicht.
+Das kann erwünscht sein, wenn eine Änderung nicht ausgerollt werden muss (z.b. Dokumentation angepasst, fixtures verändert, etc.)
+
+Um bei einem Pull-Request eine Warnung zu sehen, wenn die Version nicht erhöht wurde kann folgender Workflow verwendet werden. Es ist keine Anpassung nötig.
+```#!yaml
+name: check if project is already released
+on:
+  - pull_request
+
+jobs:
+  check:
+    runs-on: action-runner
+    steps:
+      - uses: actions/checkout@v4
+      - uses: https://gitea.puzzleyou.net/actions/release/check-is-not-released@v0
+```
+
+Bei einem Prerelease (merge in testing) muss die Version nicht angepasst werden. Das geschieht automatisch.