refaktorointia

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

@@ -0,0 +1,97 @@
+# 7. Statusraportoinnin pattern
+
+## Päätös
+
+Jokaisen jobin on raportoitava lopputulos commit-statukseen. Käytössä on kaksi
+patternia, jotka eroavat toisistaan vain raporttien julkaisun osalta.
+
+### Tool-jobit (validate, build, push, tag, check-version, report-index)
+
+```
+PENDING → työvaihe → SUCCESS (if: success) / FAILURE (if: failure)
+```
+
+```yaml
+- name: Set Gitea status to PENDING
+  run: bash .ci/scripts/report-status.sh pending "Validating..." ci-validate
+
+- 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
+```
+
+### Test-jobit (bats, cucumber)
+
+```
+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
+
+- name: Run tests
+  shell: bash
+  run: |
+    run-tests
+    EXIT=$?
+    echo "EXIT=${EXIT}" >> "${GITHUB_ENV}"
+    exit ${EXIT}
+
+- name: Publish reports
+  if: always()
+  run: bash .ci/scripts/publish-git-pages.sh suite
+
+- name: Report status
+  if: always()
+  shell: bash
+  run: |
+    if [ "${EXIT}" = "0" ]; then
+      bash .ci/scripts/report-status.sh success "Tests OK" ci-tests suite
+    else
+      bash .ci/scripts/report-status.sh failure "Tests FAILED" ci-tests suite
+    fi
+```
+
+## 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
+   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.
+
+## 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.
+
+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.