WIP 2

README.md

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