refaktorointia

docs/adr/0007-status-reporting-pattern.md

@@ -2,40 +2,32 @@
 
 ## Päätös
 
-Jokaisen jobin on raportoitava lopputulos commit-statukseen. Käytössä on kaksi
-patternia, jotka eroavat toisistaan vain raporttien julkaisun osalta.
+Gitea Actionsin natiivi job-status on ensisijainen. Commit-status API:a
+(`report-status.sh`) käytetään **vain** kun työvaihe tuottaa ulkoisen linkin
+(testiraportti, Docker registry), jota natiivistaatus ei tue.
 
-### Tool-jobit (validate, build, push, tag, check-version, report-index)
+### Tool-jobit (validate, check-version, tag-commit)
 
-```
-PENDING → työvaihe → SUCCESS (if: success) / FAILURE (if: failure)
-```
+Ei API-kutsuja. Luotetaan Gitean omaan job-statukseen.
 
 ```yaml
-- name: Set Gitea status to PENDING
-  run: bash .ci/scripts/report-status.sh pending "Validating..." ci-validate
+- uses: actions/checkout@v4
 
 - name: Do work
-  run: some-command
-
-- name: Report status SUCCESS
-  if: success()
-  run: bash .ci/scripts/report-status.sh success "OK" ci-validate
-
-- name: Report status FAILURE
-  if: failure()
-  run: bash .ci/scripts/report-status.sh failure "FAILED" ci-validate
+  run: do-something
 ```
 
 ### Test-jobit (bats, cucumber)
 
+API:a käytetään raporttilinkin upottamiseksi commit-näkymään.
+
 ```
 PENDING → testit → publish (always) → status (always, exit-koodin mukaan)
 ```
 
 ```yaml
 - name: Set Gitea status to PENDING
-  run: bash .ci/scripts/report-status.sh pending "Running tests..." ci-tests
+  run: bash .ci/scripts/report-status.sh pending "Running tests..." ci-bats
 
 - name: Run tests
   shell: bash
@@ -47,51 +39,50 @@ PENDING → testit → publish (always) → status (always, exit-koodin mukaan)
 
 - name: Publish reports
   if: always()
-  run: bash .ci/scripts/publish-git-pages.sh suite
+  run: bash .ci/scripts/publish-git-pages.sh bats
 
 - name: Report status
   if: always()
   shell: bash
   run: |
     if [ "${EXIT}" = "0" ]; then
-      bash .ci/scripts/report-status.sh success "Tests OK" ci-tests suite
+      bash .ci/scripts/report-status.sh success "Bats tests OK" ci-bats bats
     else
-      bash .ci/scripts/report-status.sh failure "Tests FAILED" ci-tests suite
+      bash .ci/scripts/report-status.sh failure "Bats tests FAILED" ci-bats bats
     fi
 ```
 
+### Build & push -jobit (docker-build-push)
+
+API:a käytetään Docker registry -linkin upottamiseksi.
+
+```
+PENDING → build → push → SUCCESS (registry-linkillä) / FAILURE
+```
+
 ## Periaatteet
 
-1. Ennen varsinaista työvaihetta asetetaan status `pending` — näin commit-näkymässä
-   näkyy heti, että jobi on käynnissä.
-2. `run`-komennon on nostettava virhe ylös — oli kyse tool-callista (docker,
-   curl, bash) tai testien ajamisessa tapahtuneesta testivirheestä.
-3. Tool-jobit käyttävät `if: success()` ja `if: failure()` — jobin sisäinen
-   tila ratkaisee suoraan kumman steppi ajetaan.
-4. Test-jobit käyttävät `if: always()` publish- ja status-stepeissä — raportti
+1. Gitea Actionsin natiivi job-status on ensisijainen. API:a käytetään vain
+   custom-linkin tarpeeseen (ADR 0004).
+2. `run`-komennon on nostettava virhe ylös — oli kyse tool-callista tai
+   testivirheestä (ADR 0008).
+3. Test-jobit käyttävät `if: always()` publish- ja status-stepeissä — raportti
    julkaistaan ja status asetetaan aina, riippumatta testin lopputuloksesta.
-5. Testiraportit julkaistaan myös virhetilanteessa, mikäli ne ovat syntyneet.
-6. Status-linkki ohjaa testiraporttiin (suite-parametri) jos raportti on
-   olemassa, muuten Gitea Actions -logiin.
+4. Testiraportit julkaistaan myös virhetilanteessa, mikäli ne ovat syntyneet.
+5. Commit-statuksen duplikaatio natiivijob-statuksen kanssa hyväksytään
+   testijobeille — se on ainoa mekanismi upottaa raporttilinkki commit-näkymään.
+6. Tool-jobit eivät käytä API:a lainkaan — ne luottavat Gitean natiiviin
+   job-statukseen.
 
 ## Tausta
 
-Aiemmassa `quality-gate.yml`:ssä käytettiin `if: always()` + sisäistä if/elseä
-myös tool-jobeissa (`steps.<id>.outcome`-tarkistus). Tämä on tarpeetonta
-kompleksisuutta työvaiheille, jotka eivät tuota erillistä raporttia — jobin oma
-tila (`success`/`failure`) on riittävä ehto.
+Aiemmin commit-status API:a käytettiin jokaisessa työvaiheessa, myös niissä
+joilla ei ollut raporttia linkitettäväksi (validate, check-version, tag-commit).
+Tämä tuotti duplikaatiota: Gitea näytti sekä natiivin `CI Main / Validate CI config
+Successful` että API-statuksen `ci-validate CI config valid`. Kehittäjälle
+molemmat kertoivat saman asian.
 
-Test-jobit tarvitsevat `if: always()`:n koska raportti on julkaistava ja status
-asetettava silloinkin kun testit epäonnistuvat. Status-viestin URL osoittaa
-suoraan raporttiin git-pagesissa, mikä on kriittinen feature virheenjäljityksessä.
-
-Pipeline-status jokaiselle vaiheelle on välttämätön, koska Gitean branch
-protection -säännöt käyttävät commit-statusta merge-estona. Jokainen
-`ci-*`-konteksti voi toimia vaadittuna statuksena PR:n sulkemiselle — jos
-yksikin status on `failure`, merge estyy. Tämä korvaa Jenkinsin
-`disableConcurrentBuilds()`- ja build gate -logiikan Gitea-natiivilla
-mekanismilla.
-
-Status-näkymä toimii myös master-haaran terveyden monitorina: Git UI:sta
-näkee suoraan yhdellä silmäyksellä onko uusin commit vihreä. Ei tarvitse
-avata CI-järjestelmän dashboardia.
+Käytännön pakko kuitenkin pakottaa API:n käyttöön testijobeissa: ilman
+raporttilinkkiä kukaan ei löydä testituloksia. Gitean natiivi job-status
+linkittää aina jobin lokiin — ei ulkoiseen raporttiin. Tämä on paras
+saatavilla oleva kompromissi.