release/README.md

# release action

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.