61 lines
3 KiB
Markdown
61 lines
3 KiB
Markdown
# Bidragsguide – W-tek Scriptbibliotek
|
||
|
||
Følg disse konvensjonene så biblioteket holder seg ryddig, trygt og enkelt å bruke.
|
||
|
||
## 1. Navnekonvensjoner
|
||
|
||
| Språk | Konvensjon | Eksempel |
|
||
|--------------|------------------------------------|-----------------------------------|
|
||
| PowerShell | `Verb-Noun.ps1` (godkjent verb, PascalCase) | `Get-DiskSpaceReport.ps1` |
|
||
| Bash/Shell | `kebab-case.sh` | `rotate-log-files.sh` |
|
||
| Python | `snake_case.py` | `export_user_report.py` |
|
||
| Batch/CMD | `kebab-case.cmd` | `map-network-drives.cmd` |
|
||
|
||
- Bruk **godkjente PowerShell-verb** (`Get-Verb`): Get, Set, New, Remove, Invoke, Update, Enable, Disable osv.
|
||
- Navnet skal beskrive hva scriptet gjør, ikke hvilket system (systemet framgår av mappen).
|
||
|
||
## 2. Mappeplassering
|
||
|
||
Plattform på toppnivå, funksjon som undermappe (se `README.md`).
|
||
- Enkelt script = én fil i riktig mappe.
|
||
- Sammensatt script (flere filer, moduler, ressurser) = egen undermappe med `README.md` basert på `templates/SCRIPT_README_TEMPLATE.md`.
|
||
|
||
## 3. Obligatorisk header
|
||
|
||
Hvert script **skal** ha en utfylt header (bruk malen for språket). Minimumsfelt:
|
||
|
||
- Kort beskrivelse (synopsis) og en lengre beskrivelse
|
||
- Alle parametere/argumenter dokumentert
|
||
- Minst ett kjøre-eksempel
|
||
- **Forfatter**, **opprettet-dato**, **versjon**
|
||
- **Plattform/krav** (f.eks. PowerShell 5.1/7, moduler, rettigheter)
|
||
- **Endringslogg** (dato, versjon, hva og hvem)
|
||
- **Tags** for søk (f.eks. `m365, entra, rapportering`)
|
||
|
||
## 4. Sikkerhet (viktig)
|
||
|
||
- **Ingen hemmeligheter i koden eller historikken.** Aldri passord, API-nøkler, tokens, sertifikater eller kundedata.
|
||
- Hent hemmeligheter via parametere, miljøvariabler eller en hemmelighetsløsning (f.eks. Windows Credential Manager, Azure Key Vault).
|
||
- Spesielt for **NinjaRMM / SentinelOne / Cove / Graph**: API-nøkler skal aldri committes. Bruk plassholdere som `$env:S1_API_TOKEN`.
|
||
- Skulle en hemmelighet ved et uhell bli committet: rull nøkkelen umiddelbart og gi beskjed – historikken må renses.
|
||
|
||
## 5. Kvalitet og kjøring
|
||
|
||
- Skriv **idempotente** script der det er mulig.
|
||
- Endringsscript skal støtte tørrkjøring: PowerShell `-WhatIf`/`-Confirm`, Bash/Python en `--dry-run`-flagg.
|
||
- Håndter feil eksplisitt (`try/catch`, `set -euo pipefail`, `try/except`) og gi tydelige exit-koder.
|
||
- Logg det som er relevant, men aldri hemmeligheter.
|
||
|
||
## 6. Git-arbeidsflyt
|
||
|
||
1. Lag en branch: `feature/<kort-beskrivelse>` eller `fix/<kort-beskrivelse>`.
|
||
2. Commit-melding: kort og beskrivende, gjerne `[plattform] handling` – f.eks. `[m365] legg til lisensrapport`.
|
||
3. Åpne en **pull request**. Minst én kollega gjennomgår før merge (firekontroll – relevant for ISO 9001/27001).
|
||
4. Oppdater `CHANGELOG.md` ved større tillegg/endringer.
|
||
|
||
## 7. Testkrav
|
||
|
||
Før merge skal scriptet være testet. Beskriv i PR-en (eller scriptets README):
|
||
- Hva som er testet
|
||
- Hvilken plattform/versjon det er testet på
|
||
- Eventuelle forutsetninger/begrensninger
|