|
3 | 3 | Denna guide beskriver de viktigaste grunderna för utveckling i detta projekt. |
4 | 4 |
|
5 | 5 | ## Innehållsförteckning |
6 | | -* [Installation](#installation-och-konfiguration) |
7 | | -* [Förutsättningar](#förutsättningar) |
8 | | -* [Utvecklingsflöde](#utvecklingsflöde) |
9 | | - * [Utveckla](#utveckla) |
10 | | - * [Pull Request-flöde](#pull-request-flöde) |
11 | | -* [Releaseprocess](#releaseprocess) |
12 | | -* [Testa och verifiera](#testa-och-verifiera) |
13 | | -* [Eventuella hinder](#eventuella-hinder) |
14 | | - |
15 | | -## Installation |
16 | | -1. Klona ned projektet, gärna från senaste release tag. |
17 | | -2. Installera alla beroenden och provkör: |
18 | 6 |
|
19 | | -```bash |
20 | | -npm install |
21 | | -npm start -- --help |
22 | | -npm start -- -f openapi.yaml |
23 | | -``` |
| 7 | +- [Installation och konfiguration](#installation-och-konfiguration) |
| 8 | + - [Förutsättningar](#förutsättningar) |
| 9 | + - [Snabbstart](#snabbstart) |
| 10 | +- [Utvecklingsflöde](#utvecklingsflöde) |
| 11 | + - [Tillgängliga kommandon](#tillgängliga-kommandon) |
| 12 | + - [Pull Request-flöde](#pull-request-flöde) |
| 13 | +- [Releaseprocess](#releaseprocess) |
| 14 | +- [Testa och verifiera](#testa-och-verifiera) |
| 15 | + |
| 16 | +## Installation och konfiguration |
| 17 | + |
| 18 | +### Förutsättningar |
| 19 | + |
| 20 | +- [mise](https://mise.jdx.dev/) - Verktygsversionshanterare |
| 21 | +- [just](https://github.com/casey/just) - Kommandokörare (installeras via mise) |
| 22 | + |
| 23 | +### Snabbstart |
| 24 | + |
| 25 | +```shell |
| 26 | +# Installera alla utvecklingsverktyg |
| 27 | +mise install |
| 28 | + |
| 29 | +# Konfigurera delade lintverktyg |
| 30 | +just setup-devtools |
24 | 31 |
|
25 | | -## Förutsättningar |
26 | | -Du bör ha följande installerat för att arbeta i projektet: |
27 | | -- Nodejs |
28 | | -- Podman och/eller Docker |
29 | | -- Git |
| 32 | +# Kör alla kvalitetskontroller |
| 33 | +just verify |
| 34 | +``` |
30 | 35 |
|
31 | 36 | ## Utvecklingsflöde |
32 | 37 |
|
33 | | -### Utveckla |
34 | | - - Skapa en ämnesgren från projektets huvudgren, oftast baserat på och namngett efter ett ärende i backlogen. |
35 | | - - feature/ny-feature |
36 | | - - fix/ny-fix |
37 | | - - Pusha dina ändringar till ämnesgrenen. |
38 | | - - Öppna en ny pull request till huvudprojektet när du känner dig klar. |
| 38 | +### Tillgängliga kommandon |
| 39 | + |
| 40 | +Kör `just` för att se alla tillgängliga kommandon. Huvudkommandon: |
| 41 | + |
| 42 | +| Kommando | Beskrivning | |
| 43 | +|----------|-------------| |
| 44 | +| `just verify` | Kör alla kontroller (lint + test) | |
| 45 | +| `just lint-all` | Kör alla linters | |
| 46 | +| `just lint-fix` | Autofixa lintproblem | |
| 47 | +| `just test` | Kör tester | |
| 48 | +| `just build` | Bygg projektet | |
| 49 | +| `just clean` | Rensa byggartefakter | |
| 50 | + |
| 51 | +#### Lintkommandon |
39 | 52 |
|
40 | | - Följ allmänna regler kring [CONTRIBUTING.md](../CONTRIBUTING.md) |
| 53 | +| Kommando | Verktyg | Beskrivning | |
| 54 | +|----------|---------|-------------| |
| 55 | +| `just lint-commits` | conform | Validera commit-meddelanden | |
| 56 | +| `just lint-secrets` | gitleaks | Skanna efter hemligheter | |
| 57 | +| `just lint-yaml` | yamlfmt | Linta YAML-filer | |
| 58 | +| `just lint-markdown` | rumdl | Linta markdown-filer | |
| 59 | +| `just lint-shell` | shellcheck | Linta shell-skript | |
| 60 | +| `just lint-shell-fmt` | shfmt | Kontrollera shell-formatering | |
| 61 | +| `just lint-actions` | actionlint | Linta GitHub Actions | |
| 62 | +| `just lint-license` | reuse | Kontrollera licensefterlevnad | |
| 63 | + |
| 64 | +#### Fixkommandon |
| 65 | + |
| 66 | +| Kommando | Beskrivning | |
| 67 | +|----------|-------------| |
| 68 | +| `just lint-yaml-fix` | Fixa YAML-formatering | |
| 69 | +| `just lint-markdown-fix` | Fixa markdown-formatering | |
| 70 | +| `just lint-shell-fmt-fix` | Fixa shell-formatering | |
41 | 71 |
|
42 | 72 | ### Pull Request-flöde |
43 | 73 |
|
44 | | -När du skickar in en PR kommer CI automatiskt att köra flera kontroller.<br/> |
| 74 | +När du skickar in en PR kommer CI automatiskt att köra flera kontroller. |
45 | 75 | För att undvika överraskningar bör du köra dessa kontroller lokalt först. |
46 | 76 |
|
47 | | -#### Köra kvalitetskontroller lokalt |
| 77 | +```shell |
| 78 | +# Kör alla kontroller |
| 79 | +just verify |
48 | 80 |
|
49 | | -1. Kör kvalitetskontrollscriptet: |
50 | | - ```shell |
51 | | - ./development/code_quality.sh |
52 | | - ``` |
53 | | -2. Åtgärda eventuella problem |
54 | | -3. Uppdatera din PR med fixarna |
55 | | -4. Verifiera att CI passerar i den uppdaterade PR:en |
| 81 | +# Eller kör endast linting |
| 82 | +just lint-all |
| 83 | + |
| 84 | +# Autofixa där det är möjligt |
| 85 | +just lint-fix |
| 86 | +``` |
56 | 87 |
|
57 | 88 | #### Detaljer för kvalitetskontroller |
58 | 89 |
|
59 | | -- **Lintning med megalinter**: BASH, Markdown, YAML, Typescript, GitHub Actions, säkerhetsskanning |
60 | | -- **Licensöverensstämmelse**: REUSE-verktyget säkerställer korrekt copyright-information |
| 90 | +- **Linting**: Shell, YAML, Markdown, TypeScript, GitHub Actions |
| 91 | +- **Säkerhet**: Hemlighetsskanning med gitleaks |
| 92 | +- **Licensefterlevnad**: REUSE-verktyget säkerställer korrekt copyright-information |
61 | 93 | - **Commit-struktur**: Conform kontrollerar commit-meddelanden för changelog-generering |
62 | | -- **Beroendeanalys**: Skannar efter sårbarheter, utdaterade paket och licensproblem |
63 | | -- **OpenSSF Scorecard**: Validerar säkerhetsbästa praxis |
64 | 94 |
|
65 | 95 | #### Hantering av misslyckade kontroller |
66 | 96 |
|
67 | 97 | Om några kontroller misslyckas i CI-pipelinen: |
68 | 98 |
|
69 | 99 | 1. Granska CI-fel-loggarna |
70 | | -2. Kör kontrollerna lokalt för att återskapa problemen |
| 100 | +2. Kör `just verify` lokalt för att återskapa problemen |
71 | 101 | 3. Gör nödvändiga fixar i din lokala miljö |
72 | 102 | 4. Uppdatera din Pull Request |
73 | 103 | 5. Verifiera att alla kontroller passerar i den uppdaterade PR:en |
74 | 104 |
|
75 | 105 | ## Releaseprocess |
76 | | -Releaseprocessen hanteras automatiskt av maintainer-teamet via intern dokumentation. |
| 106 | + |
| 107 | +Releaseprocessen hanteras automatiskt av maintainer-teamet via intern dokumentation. |
77 | 108 |
|
78 | 109 | ## Testa och verifiera |
| 110 | + |
79 | 111 | Efter varje release, pre- eller stabil, bör funktionaliteten testas och verifieras. |
80 | 112 |
|
81 | | -### Testa mot publicerat npm paket |
82 | | -Kör följande kommando mot den version av verktyget som ska testas: |
83 | | -```bash |
84 | | -npx @diggsweden/rest-api-profil-lint-processor@<version> -f openapi.yaml -l raplp.log --dex avstamning.xlsx |
85 | | -``` |
| 113 | +### Testa mot publicerat npm-paket |
86 | 114 |
|
87 | | ---- |
| 115 | +Kör följande kommando mot den version av verktyget som ska testas: |
88 | 116 |
|
89 | | -#### Test av image med podman/docker |
90 | | -Kör följande kommandon med den version av verktyget som ska testas: |
91 | 117 | ```bash |
92 | | -podman run -it -v $(pwd):/data ghcr.io/diggsweden/rest-api-profil-lint-processor:<version> -f /data/openapi.yaml -l /data/raplp.log --dex /data/avstamning.xlsx |
| 118 | +npx @diggsweden/rest-api-profil-lint-processor@<version> -f openapi.yaml -l raplp.log --dex avstamning.xlsx |
93 | 119 | ``` |
94 | 120 |
|
95 | | -> För alla kommandon bör ***podman*** kunna ersättas med ***docker*** om så önskas. |
| 121 | +### Test av image med podman/docker |
96 | 122 |
|
97 | | -I en terminal kör: |
98 | | - ```bash |
99 | | - podman run --rm -it -v $(pwd):/data ghcr.io/diggsweden/rest-api-profil-lint-processor:<version> -f /data/openapi.yaml |
100 | | - ``` |
101 | | -* Där data motsvarar den katalog i containern som du vill att nuvarande katalog `\$(pwd)` mountas in i, containern får tillgång till dina filer i `\$(pwd)`. |
102 | | -* Där `openapi.yaml` motsvarar den filen som du vill applicera valideringen på. |
103 | | -* Där \<VERSION> motsvarar den version av rest-api-profilen som du vill nyttja. |
| 123 | +Kör följande kommandon med den version av verktyget som ska testas: |
104 | 124 |
|
105 | | -> Notera: Sökvägar kan hanteras olika beroende på miljö: |
106 | | -> - Podman (Linux/macOS/WSL): -v $(pwd):/app/example |
107 | | -> - Docker (PowerShell): -v "${PWD}:/app/example" |
108 | | -> - Docker (CMD): -v %cd%:/app/example |
109 | | -
|
110 | | -Exempel |
111 | | - ```bash |
112 | | - podman run --rm -it -v $(pwd):/data ghcr.io/diggsweden/rest-api-profil-lint-processor:<version> -f /data/openapi.yaml -l /data/raplp.log --dex /data/avstamning.xlsx |
113 | | - ``` |
114 | | - |
115 | | -Vid eventuella fel och du inte hittar rap-lp-error.log kan du behöva köra kommandot via containern enligt den alternativa instruktionen nedan.<br> |
116 | | -Se till att containern har rättigheter att skriva till den katalog som du mountar, se [Skrivåtkomst till mount från container](#skrivåtkomst-till-mount-från-container). |
117 | | - |
118 | | -#### Alternativ att köra ifrån containern |
119 | | -1. Starta en podman container: |
120 | | - ```bash |
121 | | - podman run --rm -it --entrypoint /bin/sh -v $(pwd):/app/data ghcr.io/diggsweden/rest-api-profil-lint-processor:<version> |
122 | | - ``` |
123 | | -2. Kör din validering ifrån containern: |
124 | | - ```bash |
125 | | - npm start -- -f /data/openapi.yaml |
126 | | - ``` |
127 | | -3. Lägg på önskade flaggor enligt tidigare exempel. |
128 | | - |
129 | | -Exempel: |
130 | 125 | ```bash |
131 | | -podman run --rm -it --entrypoint /bin/sh -v $(pwd):/app/data ghcr.io/diggsweden/rest-api-profil-lint-processor:<version> |
132 | | -
|
133 | | -/app: npm start -- -f data/openapi.yaml -l data/raplp.log --dex data/avstamning.xlsx # skriver till din nuvarande katalog |
| 126 | +podman run -it -v $(pwd):/data ghcr.io/diggsweden/rest-api-profil-lint-processor:<version> -f /data/openapi.yaml -l /data/raplp.log --dex /data/avstamning.xlsx |
134 | 127 | ``` |
135 | 128 |
|
136 | | -## Eventuella hinder |
137 | | - |
138 | | -#### Access till registry |
139 | | - |
140 | | -Du kan behöva ett Personal Access Token (PAT) för din användare i github för att kunna hämta images från Github Container Registry (GHCR) och Github Packages, se [FAQ i readme](../README.md/#hur-skapar-jag-ett-github-personal-access-token-pat). |
141 | | - |
142 | | -#### Skrivåtkomst till mount från container |
143 | | -Vid körningar med podman och docker i kombination med flaggor som sparar information till filer kan det uppstå problem kring skrivrättigheter som gör att filer inte dyker upp som önskat. Filerna kan finnas i containern men dyker inte i den mountade katalogen som specificerats. Se [FAQ i readme](../README.md/#skrivåtkomst-till-mount-från-container). |
144 | | - |
| 129 | +> För alla kommandon bör **podman** kunna ersättas med **docker** om så önskas. |
145 | 130 |
|
| 131 | +> Notera: Sökvägar kan hanteras olika beroende på miljö: |
| 132 | +> - Podman (Linux/macOS/WSL): `-v $(pwd):/app/example` |
| 133 | +> - Docker (PowerShell): `-v "${PWD}:/app/example"` |
| 134 | +> - Docker (CMD): `-v %cd%:/app/example` |
0 commit comments