Gå til hovedinnhold

GUI-løsninger for Changelog-administrasjon

Oversikt​

Dette dokumentet presenterer ulike alternativer for å implementere en grafisk brukergrensesnitt (GUI) for å legge til og administrere changelog-oppføringer. Løsningene varierer i kompleksitet, vedlikeholdsbehov og brukervennlighet.

1. Integrert Admin-panel i Nettsiden​

Beskrivelse​

En innebygd administrasjonsside direkte i dokumentasjonsportalen, tilgjengelig via f.eks. /admin/changelog.

Teknisk implementering​

  • React-basert skjema integrert i Docusaurus
  • Autentisering via eksisterende OIDC/Feide-integrasjon
  • Skjemafelt for alle metadata (type, tittel, sammendrag, områder, osv.)
  • Live forhåndsvisning av hvordan oppføringen vil se ut
  • Lagring direkte til Git via API eller backend-tjeneste

Fordeler​

  • ✅ Sømløs integrasjon med eksisterende design
  • ✅ Ingen eksterne verktøy
  • ✅ Konsistent brukeropplevelse
  • ✅ Live forhåndsvisning med samme styling

Ulemper​

  • ❌ Krever implementering av autentisering/autorisasjon
  • ❌ Må bygge backend for Git-operasjoner
  • ❌ Vedlikeholdsbyrde øker

Estimert utviklingstid​

2-3 uker for fullstendig implementering

2. GitHub/GitLab Web-grensesnitt​

Beskrivelse​

Bruke den innebygde filredigeringen i GitHub/GitLab med maler og automatisering.

Teknisk implementering​

  • Alternativ A: "Create new file" med forhåndsdefinert mal
  • Alternativ B: GitHub Issues med mal som trigger GitHub Actions
  • Alternativ C: GitLab Web IDE med snippets
  • Automatisk generering av MDX-fil via CI/CD pipeline

Fordeler​

  • ✅ Versjonskontroll innebygd
  • ✅ Ingen ekstra infrastruktur
  • ✅ Audit trail via Git-historikk
  • ✅ Kan bruke branch protection og review-prosess

Ulemper​

  • ❌ Krever tilgang til repository
  • ❌ Ikke optimalisert for ikke-tekniske brukere
  • ❌ Begrenset mulighet for validering
  • ❌ Ingen live forhåndsvisning

Estimert utviklingstid​

3-5 dager for oppsett med Actions/CI

3. Headless CMS-integrasjon​

Beskrivelse​

Koble til et dedikert innholdshåndteringssystem for profesjonell content management.

Alternativer​

  • Strapi: Open source, self-hosted, Node.js-basert
  • Directus: Open source, database-first approach
  • Sanity: Cloud-basert, kraftig men har kostnader
  • Contentful: Enterprise-ready, men dyrt

Teknisk implementering​

  • CMS kjører som separat tjeneste
  • Webhook trigger bygeprosess ved endringer
  • API-integrasjon for å hente changelog-data
  • Eller: Generer MDX-filer ved build

Fordeler​

  • ✅ Profesjonelt brukergrensesnitt
  • ✅ Innebygd brukeradministrasjon
  • ✅ Revisjon og versjonering
  • ✅ Mulighet for godkjenningsflyt
  • ✅ Rich text editor med formatering
  • ✅ Mediehåndtering innebygd

Ulemper​

  • ❌ Ekstra tjeneste å drifte
  • ❌ Økt kompleksitet
  • ❌ Potensielle kostnader (for cloud-løsninger)
  • ❌ Synkroniseringsproblemer mellom CMS og Git

Estimert utviklingstid​

1-2 uker inkludert oppsett og integrasjon

4. VS Code Extension​

Beskrivelse​

En tilpasset utvidelse for Visual Studio Code med integrert skjema.

Teknisk implementering​

  • Webview panel med React-skjema
  • Direkte filmanipulering i arbeidsområdet
  • IntelliSense for metadata-felter
  • Validering og auto-complete

Fordeler​

  • ✅ Integrert i utviklingsmiljøet
  • ✅ Ingen kontekstbytte for utviklere
  • ✅ Kan validere mot schema
  • ✅ Git-integrasjon via VS Code

Ulemper​

  • ❌ Kun for VS Code-brukere
  • ❌ Krever teknisk kompetanse
  • ❌ Vedlikehold av extension
  • ❌ Distribusjon til teamet

Estimert utviklingstid​

1-2 uker for grunnleggende funksjonalitet

5. Standalone Desktop-applikasjon (Electron)​

Beskrivelse​

En dedikert desktop-applikasjon for changelog-administrasjon.

Teknisk implementering​

  • Electron-app med React/Vue
  • Lokal Git-integrasjon
  • Offline-støtte med synkronisering
  • Drag-and-drop for bilder/vedlegg

Fordeler​

  • ✅ Rik, native brukeropplevelse
  • ✅ Fungerer offline
  • ✅ Kan ha avanserte funksjoner
  • ✅ Ingen nettleser-begrensninger

Ulemper​

  • ❌ Må distribueres og installeres
  • ❌ Plattform-spesifikke problemer
  • ❌ Oppdateringer må håndteres
  • ❌ Størst vedlikeholdsbyrde

Estimert utviklingstid​

3-4 uker for MVP

6. Statisk nettside med GitHub API​

Beskrivelse​

En enkel nettside som bruker GitHub API for å opprette pull requests.

Teknisk implementering​

  • Statisk HTML/JS hostet på GitHub Pages
  • Client-side JavaScript med GitHub REST/GraphQL API
  • Personal Access Token eller GitHub App
  • Genererer MDX og oppretter PR

Fordeler​

  • ✅ Ingen backend nødvendig
  • ✅ Kan hostes gratis
  • ✅ Enkel å vedlikeholde
  • ✅ Review-prosess via PR

Ulemper​

  • ❌ Token-håndtering (sikkerhet)
  • ❌ Begrenset til GitHub-brukere
  • ❌ Ingen server-side validering
  • ❌ CORS-begrensninger

Estimert utviklingstid​

3-5 dager for fungerende prototype

7. Chat-integrasjon (Slack/Teams Bot)​

Beskrivelse​

En chatbot som lar brukere legge til changelog via Slack eller Teams.

Teknisk implementering​

  • Slash-kommando: /changelog add
  • Modal/dialog for input
  • Bot som committer til Git
  • Varslinger om nye oppføringer

Fordeler​

  • ✅ Der teamet allerede er
  • ✅ Lav terskel for bruk
  • ✅ Varsling innebygd
  • ✅ Kan integreres med godkjenningsflyt

Ulemper​

  • ❌ Platform-låst
  • ❌ Begrenset UI-fleksibilitet
  • ❌ Krever bot-hosting
  • ❌ Ikke egnet for lengre tekster

Estimert utviklingstid​

1 uke per plattform

8. CLI med Interaktive Prompts​

Beskrivelse​

Et kommandolinje-verktøy med veiledede spørsmål for hver felt.

Teknisk implementering​

npm run changelog:add
  • Node.js script med inquirer eller prompts
  • Interaktive spørsmål med validering
  • Auto-generering av ID og timestamp
  • Mulighet for templates for ulike typer

Eksempel på flyt​

? Hva slags endring? (Use arrow keys)
❯ new-feature
  improvement
  bug-fix
  breaking-change
  
? Tittel: Ny funksjonalitet for brukeradministrasjon

? Kort sammendrag: La til mulighet for bulk-import av brukere

? Områder (kommaseparert): brukeradmin, import

? Målgruppe: (Press space to select)
◯ students
◉ administrators
◯ developers

? Breaking change? (y/N) n

✅ Changelog entry created: src/content/changelog/2024-01-15-brukeradmin.mdx
? Commit og push? (Y/n) y

Fordeler​

  • ✅ Raskt å implementere
  • ✅ Enkel validering
  • ✅ Kan automatisere git-operasjoner
  • ✅ Template-støtte

Ulemper​

  • ❌ Kun kommandolinje
  • ❌ Krever teknisk kunnskap
  • ❌ Ingen forhåndsvisning
  • ❌ Ikke egnet for alle brukere

Estimert utviklingstid​

1-2 dager

Anbefalt Strategi: Trinnvis Implementering​

Fase 1: Quick Win (Uke 1)​

Implementer CLI-verktøy (#8) for umiddelbar nytte:

  • Rask implementering
  • Dekker utviklernes behov
  • Gir erfaring med datamodellen

Fase 2: Bredere Tilgang (Uke 2-3)​

Legg til Statisk nettside med GitHub API (#6):

  • Enkel web-formular
  • Autentisering via GitHub
  • Oppretter PR for review
  • Tilgjengelig på /changelog/new

Fase 3: Evaluering og Utvidelse (Måned 2-3)​

Basert på erfaringer, vurder:

  • Headless CMS hvis mange ikke-tekniske bidragsytere
  • Admin-panel hvis tett integrasjon ønskes
  • Chat-bot hvis teamet primært bruker Slack/Teams

Beslutningskriterier​

Spørsmål å vurdere:​

  1. Hvem skal legge til changelog-oppføringer?

    • Kun utviklere → CLI eller VS Code
    • Også produkteiere/andre → Web GUI eller CMS

  2. Hvor ofte legges det til oppføringer?

    • Daglig → Optimalisert flyt viktig
    • Ukentlig/månedlig → Enkelhet viktigere

  3. Behov for godkjenningsflyt?

    • Ja → GitHub PR eller CMS med workflow
    • Nei → Direkte commit OK

  4. Teknisk kompetanse i teamet?

    • Høy → CLI/Git-baserte løsninger
    • Variert → GUI nødvendig

  5. Vedlikeholdskapasitet?

    • Begrenset → Enkle løsninger
    • God → Kan vurdere avanserte alternativer

Kostnader og Ressursbehov​

LøsningUtviklingstidVedlikeholdInfrastrukturLisenskost
CLI1-2 dagerLavIngenGratis
GitHub Web3-5 dagerLavIngenGratis
Statisk Web3-5 dagerLavGitHub PagesGratis
VS Code Ext1-2 ukerMiddelsIngenGratis
Admin Panel2-3 ukerHøyEksisterendeGratis
Headless CMS1-2 ukerMiddelsServer/Cloud0-500$/mnd
Electron App3-4 ukerHøyIngenGratis
Chat Bot1 ukeMiddelsBot hosting0-50$/mnd

Konklusjon​

For rask verdi med minimal investering, anbefales en kombinasjon av CLI-verktøy og enkel web-formular. Dette gir både effektivitet for utviklere og tilgjengelighet for andre bidragsytere, uten betydelig vedlikeholdsbyrde.

Dersom changelog blir en kritisk del av arbeidsflyten, kan investering i enten integrert admin-panel eller headless CMS vurderes på sikt.