Beslutninger for FS

I forbindelse med utviklingen av FS taes det mange beslutninger for utvikling og forvaltning av tjenester. Denne siden gir en oversikt over beslutninger vi allerede har gjort, samt beslutninger som ligger til vurdering. Disse beslutningene er gjeldene for alle applikasjoner og tjenester som inngår i FS-plattformen samt basisapplikasjonene for FS som Sikt skal levere.

Beslutningslogg

Besluttet	Beslutningsdokument	Beslutning
2024-03-14	Flytting av dokumentasjon	Vi flytter dokumentasjon til studieadministrasjon.sikt.no
2023-09-01	Bruk av GraphQL-klienter i basisapplikasjonene	Vi skal bruke veletablerte GraphQL-klienter som støtter fragmenter i basisapplikasjonene våre
2023-06-16	Feature freeze på Arbeidslivsportalen ALP	Vi har innført feature freeze på Arbeidslivsportalen ALP
2023-06-14	Innføre Playwright testrammeverk	Vi tar i bruk Playwright som testrammeverk.
2023-04-14	Next.js som frontendrammeverk	Vi tar i bruk Next.js som frontendrammeverk.
2023-03-28	Beslutningsprosess for FS	Vi innfører en beslutningprosess som baserer seg på beslutningsdokumenter i Markdown og merge requests i GitLab
2022-12-17	Standardisere på GraphQL	FS-plattformen skal tilgjengeliggjøre all data og funksjonalitet for FS i et enhetlig GraphQL API
2021-10-15	Pilotere GraphQL ➡️ Standardisere på GraphQL	Vi gjennomfører en pilot av GraphQL med den hensikt å avdekke om dette er en egnet standard for tilgjengeliggjøring av informasjon og funksjonalitet fra FS til Sikt, sektoren og privat næring.

Se listen over beslutningsforslag i GitLab for en til enhver tid oppdatert liste over beslutninger som vurderes/diskuteres for FS-plattformen.

Beslutningsprosess

Hver beslutning eksisterer som et eget dokument i denne katalogen. Dette dokumentet må skrives i tråd med retningslinjene og prosessen som beskrives under.

Vi benytter oss av GitLab som prosesshåndteringsverktøy for å fatte beslutninger. Initiativtaker må utføre følgende steg for å foreslå en beslutning:

1. Opprette en branch fra main-branchen fs-plattform-repoet
2. Legge til beslutningsdokumentet i /docs/beslutninger/-katalogen
3. Oppdatere beslutningsloggen i /docs/beslutninger/README.md-filen
4. Opprette en merge requests
5. Merke merge requesten med Beslutning-labelen

I merge requesten vil man få tilbakemeldinger, spørsmål og push back. Dette svares ut ved at beslutningsdokumentet oppdateres og forbedres. Dersom vi ikke anser den foreslåtte beslutningen som relevant vil merge requesten kunne bli avvist, noe som i praksis innebærer at ingen beslutning blir tatt.

Dersom vi anser den foreslåtte beslutningen som relevant, men konklusjonen avviker fra det opprinnelige forslaget, så vil beslutningsteksten oppdateres. Dermed beslutter vi noe annet enn det opprinnelige forslaget.

Merk at det er produktområdeleder (POL) for FS som har beslutningsmyndighet. Hun har forøvrig delegert denne myndigheten, slik at ikke-kontroversielle beslutninger som følger allerede etablerte arkitekturprinsipper kan fattes effektivt. Det er arkitektene i FS sitt ansvar å sørge for at POL blir involvert ved behov og til enhver tid er orientert om hvilke beslutninger som fattes.

Erstatte beslutninger

Etterhvert som vi lærer vil det bli nødvendig å gjøre om beslutninger. Dette skjer som del av vanlig beslutningsprosess, med følgende tillegg:

1. Oppdater beslutningsdokument-kolonnen for beslutningen som erstattes ved å:
   1. Stryk ut lenken til det gamle beslutningsdokumentet vha <s>-elementet.
   2. Sett inn et pil-mot-høyre-ikon ved hjelp av :arrow_right:.
   3. Sett inn lenken til det nye beslutningsdokumentet som erstatter beslutningen.
2. Stryk ut beslutning-kolonnen for beslutningen som erstattes vha <s>-elementet.
3. Legg til filnavnet til den nye beslutningen i erstattet av-feltet i dokumentet som erstattes.
4. Legg til filnavnet til beslutningen som erstattes i erstatter-feltet i det nye beslutningsdokumentet.

Annullere beslutninger

Noen ganger fatter man beslutninger som det viser seg at man ikke skulle gjort. I slike tilfeller kan man ha behov for å annullere beslutningen, uten at det kommer inn en ny beslutning som erstatter den gamle. Dette skjer ved at man lager en merge request med følgende endringer:

1. Stryk ut innholdet av dokument- og beslutning-kolonnen i beslutningsloggen ved å putte innholdet inn i <s>-element.
2. Legg til begrunnelse for annulleringen i annullert-feltet i beslutningsdokumentet som annulleres

Beslutningsdokument

Beslutningsdokumentet er en form for Architecture Decision Record. Vi viser til Michael Nygard sin beskrivelse av hva dette innebærer. Poenget er at beslutningsdokumenter skal være så korte som mulig, samtidig som de inneholder nok informasjon til at andre kan forstå beslutningen i ettertid.

Beslutningsdokumentene skal skrives i Markdown (CommonMark) og ha en innledningsblokk i YAML som inneholder minst de påkrevde feltene fra tabellen under. Filnavnet skal være {beslutningsdato}-{slugified title}.md og dokumentet skal ligge i beslutninger-katalogen. Merk at vi normaliserer navnet ved hjelp av webtjenesten slugify fordi det kommer til å bli mange filer og at denne normaliseringen vil gjøre det enklere å navigere i katalogen.

Felt	Påkrevd	Forklaring	Eksempel
slug	Ja	Filnavnet til beslutningsdokumentet.	2023-03-28-beslutningsprosess-for-fs.md
title	Ja	Et kort navn som sier noe om hva som besluttes. Helst i form av en substantivfrase.	Beslutningsprosess for FS
beslutning	Ja	En oppsummering av beslutningen i aktiv stemme som oppsummerer hva som er blitt besluttet.	Vi innfører en beslutningprosess som baserer seg på beslutningsdokumenter i Markdown og merge requests i GitLab
beslutningsdato	Ja	Dato for når beslutningen ble fattet, formatert som YYYY-MM-DD.	2023-03-28
merge request	Ja	URL til merge requesten hvor beslutningen ble fattet.	https://gitlab.sikt.no/fs/fs-plattform/-/merge_requests/379
erstatter		Filnavnet til beslutningen som erstattes av gjeldende beslutning. Dersom flere beslutninger erstattes gjentas feltet flere ganger.
erstattet av		Filnavnet til beslutningen som gjeldende beslutningen har blitt erstattet av.
annullert		Kort begrunnelse for hvorfor beslutningen har blitt annullert.	Beslutningen strider mot føringer fra UA.

Etter innledningsblokken følger dokumentets innhold i markdown. Dokumentet skal begynne med innholdet i feltet beslutning i innledningsblokken som første paragraf. Deretter følger eventuelt flere paragrafer som detaljerer beslutningen. Til slutt kommer følgende seksjoner:

Tittel	Forklaring
Kontekst	En beskrivelse av situasjonsbildet som lå til grunn når beslutningen ble tatt
Konsekvenser	En beskrivelse av det resulterende situasjonsbildet som følger av å implementere beslutningen.

Hvor mye brødtekst som trengs følger av:

1. Hvor store konsekvenser (kostnad) som følger av beslutningen
2. Hvor kontroversiell beslutningen er

Vi anbefaler at man alltid begynner kort og enkelt. Da vil det komme frem i merge request-prosessen hva som eventuelt mangler og må legges til før beslutningen skal kunne bli fattet.

Kjente problemer med dagens løsning

Det er dessverre noen begrensninger i publiseringsverktøyet vårt som vi ikke har løst enda.

1. Beslutningsloggen skal kunne genereres automatisk.
2. Vi må sette feltene /slug/ og /title/ for at dokumentene skal få riktig URL og tittel.
3. Vi må gjenta innholdet i beslutningsfeltet fra innledningsblokken.