Merge pull request 'README geschrieben' (!1) from doc into master

Reviewed-on: #1

README.md

@@ -1,3 +1,196 @@
 # release action
+Gitea/Github-Action, die hilft das Veröffentlichen von Projekten zu
+automatisieren.
 
-TODO document usage
+## 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](/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.