1. Indledning

Dette dokument beskriver krav for frontendleverancer til INSP platformen. Kravende er gældene for udviklingen af komponenter rettet mod nye leverancer til projektet sammen ændringer til eksisterende komponenter.

INSP Platformen overholder som udgangspunkt de krav der gælder NSP platformen, men dette dokument beskriver de ekstra regler der skal overholdes og refererer til eksisterende regler hvor det giver mening.

Disse regler er skabt på baggrund arkitekturprincipper som beskrevet i Arkitekturprincipper for iNSP løsninger

I arkitekturprincipperne refereres der til Reactive Manifesto: https://www.reactivemanifesto.org/ og "The Twelve Factor App” https://12factor.net/

Hvor ovenstående principper giver mening i forbindelse med frontend udvikling er disse specifikt udspecificeret og beskrevet.

De her beskrevne krav og anbefalinger skal ses som retningslinjer for at skabe en homogen platform, hvor mange forskellige komponenter kan sam-eksistere og fungere i et driftet miljø. Reglerne er fastsat ud fra hensyn til at udviklere til NSP projektet har en stor grad af frihed og samtidig understøtter modtagelsen af komponenter med henblik på kvalitetskontrol af NSP platformen.

Projekter, der skal levere nye komponenter til NSP platformen, skal fastholde, hvilken version af husreglerne der leveres i henhold til. Versionen registreres i OAT beskrivelserne. Læs mere om OAT her.

Såfremt leverandører ønsker at afvige fra kravene i forbindelse med komponent leverancer indledes en dialog med NSP platformen. Specielle begrundede behov tilgodeses så vidt muligt. Dette vil også kunne aftales via OAT.

Skriv til denne email adresse: operator@nspop.dk

Ting der skal besluttes og dokumenteres under OAT afklaring indeholder:

• browser targets (IE9+, edge, Chrome, Firefox, Safari etc.)

• Styling krav - UX krav

• Accessibility krav (support for blinde/svagtseende etc.)

• Krav til skærm opløsning

• Krav til GUI komponent test (Det er op til projektet at finde ud af hvordan GUI skal testes. Da klient projekterne har vidt forskellige formål for vidt forskellige brugergrupper, er det svært at sætte fælles krav for dette.)

1.1 Dokument status

Referer til https://www.nspop.dk/display/public/web/Husregler+for+udvikling+til+NSP 1.1 Dokument status

1.2 Krav og referencer

Referer til https://www.nspop.dk/display/public/web/Husregler+for+udvikling+til+NSP 1.2. Krav og referencer

1.3. Begreber og forkortelser

Referer til https://www.nspop.dk/display/public/web/Husregler+for+udvikling+til+NSP 1.3. Begreber og forkortelser

2. Design Krav

Principper for webudvikling

Byg så vidt muligt på best practises og eksisterende libraries. Det er nemmere at checke mindre kode og kvaliteten er højere over tid.

Platformen er komplex:

Benyt tools så meget som muligt til generering af byg til webpack.

Eksempel:

Angular https://angular.io/guide/setup-local

React https://create-react-app.dev/docs/getting-started/

Script er svære at vedligeholde:

Benyt tools så meget som muligt til validering af kode og style (eslint, htmlhint)

Komplexiteten af HTML er høj:

Benyt tools som lighthouse til at optimere visning.

Lighthouse https://developers.google.com/web/tools/lighthouse

Standard library er ikke eksisterende:

Benyt libraries så meget som muligt til funktionalitet der kræver mere end en simpel funktion.

Det skal være NPM pakker enten fra NPM registry NSP Nexus.

Benyt semantic versioning til versionering af projekter

NPM forventer pakker er semantisk versioneret, og standarden skal derfor overholdes. Se https://semver.org/.

Arkitektur

Da frontend verdenen er meget fragmenteret forventes det at man benytter sig af etablerede tools til at opbygge sin platform. Disse værktøjer har oftest en holdning til applikationsarkitektur, og vil som udgangspunkt være den anbefalede vej at gå. Det er velovervejede værktøjer man kommer ikke på afveje ved at følge dem.

Det forventes der kan argumenteres for den kode struktur som er anvendt i projektet. NSP projektet ligger vægt på at der er en fin opdeling af ansvarsområder. Som eks. skal services, api integrationer og gui komponenter ikke være blandet. Der "kan" komme differentierede krav til coverage og tests mm. for de forskellige ansvarsområder. De sænkede krav kan kun komme i spil hvis ansvarsområderne kan lokaliseres.

2.1 Platform

NSP Projektet stiller et NSP Docker image til rådighed for udvikling og test. Dog skal der tages hensyn til at platformen kan ændre sig inden endelig release.

Leverancen skal ske som et Docker image samt tilhørende Docker Compose filer. Se NSP Continuous Integration & Delivery for yderligere detaljer.

Inden leverancen afleveres til NSP projektet, skal den kunne bygge i node LTS version via et Jenkins job. I skrivende stund 12.16.1.

Applikationsstack

Understøttede versioner:

• Angular skal være version 9 (nyeste)

• React skal være version 16 (nyeste)

• Nyere versioner efter aftale med  NSP Projektet

Kode forventes at blive lintet (eslint, som minimum "extends: "plugin:@typescript-eslint/recommended",  minimums konfigurationer kan leveres af NSP projektet). Se typescript-eslint readme for opsætning af eslint typescript parser.

Sprog versioner:

• Hvis Angular 9: Typescript version skal følge Angular 9 anbefalinger som er 3.8 serien.

• Hvis React+Typescript: Typescript skal være 3.8 eller nyere.

• Nyere versioner efter aftale med NSP Projektet

2.2 Anvendelse af kodebiblioteker

npx npm-check --no-color --no-emoji

Se https://12factor.net/ Punkt 2 for yderligere uddybning

Licenser

npx license-checker --production --onlyAllow 'MIT;ISC;Apache-2.0;0BSD' --summary

Positiv Listen inkluderer:

https://opensource.org/licenses/MIT

Hvilket dækker både Angular og React.

2.3 Konfiguration

Se https://12factor.net/ Punkt 3 for yderligere udddybning.

2.4 Logning

3. Krav til udviklingsværktøjer og metode

3.1 Værktøjer

Kravet er i skrivende stund at dette gøres med webpack, konfigureret svarende til create-react app / angular cli, andet kan aftales med projektet.

3.2 Nexus

NSP projektet stiller en NPM registry til rådighed i Nexus (https://nexus.nspop.dk/). Denne skal benyttes til leverandør libraries. 

Regler for brug af Nexus specificeres udenfor dette dokument.

TODO: siden er endnu ikke offentliggjort, link her når den bliver det.

3.3 Byg

Da node versionen skifter hele tiden bør man stræbe efter at bruge seneste LTS version på leverance tidspunktet.

3.4 Continuous integration

Referer til https://www.nspop.dk/display/public/web/Husregler+for+udvikling+til+NSP 3.4 Continuous integration

4. Krav til Test metode og værktøjer

Alle afhængigheder skal under test afvikling være stubbet ud med mocks, således tests kan afvikles i en container uden afhængigheder på NSP Projektets byggemiljø. Automatiserede GUI tests vil dog ofte kræve en browser at blive afviklet i. Det er vigtigt at man kan afvikle disse for sig.

4.1. Unit Test

Afvikling af test er en del af bygge og release processen, og skal indgå direkte i bygget.

4.2. Code coverage - overordnet

Der er fra SDS’s side sat et mål for code coverage for leverancer. Dette tal kan variere afhængigt af hvilket værktøj og opsætning, der benyttes.

Desuden kan dele af leverancer fravælges at blive dækket; f.eks. fordi en del kode er genereret, eller hvis UI test er for omfattende i forhold til gevinst. I medfølgende dokumentation, under beskrivelse af genereringen af code coverage, bør dette være beskrevet, efter aftale med NSP projektet.

5. Krav til leverance og installation

Referer til https://www.nspop.dk/display/public/web/Husregler+for+udvikling+til+NSP 5. Krav til leverance og installation.

6. Krav til driftsmæssige forhold

På nuværende tidspunkt er der ingen driftsmæssige krav.

7. Krav til dokumentation

Referer til https://www.nspop.dk/display/public/web/Husregler+for+udvikling+til+NSP 7. Krav til dokumentation.

8. Krav til ændringer

Referer til https://www.nspop.dk/display/public/web/Husregler+for+udvikling+til+NSP 8. Krav til ændringer.

9. Ændringslog

10. Appendix

10.1 Licens

Referer til https://www.nspop.dk/display/public/web/Husregler+for+udvikling+til+NSP 10.1 Licens