100 lines
4.5 KiB
Markdown
100 lines
4.5 KiB
Markdown
# Beheer, wijzigingen en architectuurevolutie
|
|
|
|
## Deze documentatieset importeren
|
|
|
|
Start de import vanuit de pakketmap met dezelfde datamap als de wiki:
|
|
|
|
```text
|
|
racket architecture/import.rkt --data ./wiki-data --author "Hans Dijkema"
|
|
```
|
|
|
|
Voer eerst een controle zonder inhoudswijzigingen uit:
|
|
|
|
```text
|
|
racket architecture/import.rkt --data ./wiki-data --dry-run
|
|
```
|
|
|
|
De import valideert alle bronbestanden, interne links, CMap-embeds, node-id's en connector-endpoints voordat hij wiki-inhoud schrijft. Daarna maakt hij de twaalf pagina's onder namespace `racket-wiki` en twee CMaps aan of werkt hij ze bij.
|
|
|
|
## Bescherming van lokale wijzigingen
|
|
|
|
Iedere geïmporteerde pagina en CMap bevat een bronhash. Bij herimport wordt de actuele inhoud opnieuw gehasht.
|
|
|
|
- Ongewijzigde geïmporteerde inhoud kan veilig naar de nieuwe pakketversie worden bijgewerkt.
|
|
- Inhoud die al exact overeenkomt, krijgt geen zinloze extra versie.
|
|
- Handmatig gewijzigde inhoud wordt als `skipped-modified` gemeld en blijft staan.
|
|
- Alleen `--overwrite-modified` vervangt bewust zo'n lokale wijziging.
|
|
|
|
Gebruik overschrijven pas na vergelijking met de pagina- of CMaphistorie:
|
|
|
|
```text
|
|
racket architecture/import.rkt --data ./wiki-data \
|
|
--author "Hans Dijkema" --overwrite-modified
|
|
```
|
|
|
|
De importmodule gebruikt de normale procedures uit `storage.rkt` en `cmap-storage.rkt`. Daardoor ontstaan gewone onveranderlijke versies en blijven optimistic locking en afgeleide pagina-indices actief. De import schrijft geen eigen SQL buiten die opslaglaag.
|
|
|
|
## Bron aanpassen
|
|
|
|
De bron staat onder `architecture/`:
|
|
|
|
```text
|
|
architecture/
|
|
manifest.rktd
|
|
import.rkt
|
|
pages/
|
|
cmaps/
|
|
```
|
|
|
|
Voeg een pagina of CMap eerst aan `manifest.rktd` toe en maak daarna het genoemde bestand. Alle architectuurpagina's gebruiken expliciete Markdown-links naar `racket-wiki:...`. Een ingesloten kaart gebruikt `{{cmap:racket-wiki-...}}` op een eigen regel.
|
|
|
|
Voer na een wijziging uit:
|
|
|
|
```text
|
|
raco test architecture/import.rkt
|
|
racket architecture/import.rkt --data ./wiki-data --dry-run
|
|
```
|
|
|
|
## Releasebeheer
|
|
|
|
`info.rkt` is de primaire softwareversie. Frontenddiagnostiek bevat dezelfde versie om een browserfout aan het geleverde component te kunnen koppelen. De README houdt een beknopte chronologische changelog bij.
|
|
|
|
Een releasepakket bevat broncode, statische basisbestanden, Scribble-documentatie en architectuurbronnen. Het bevat niet:
|
|
|
|
- `wiki-data` of `database.rktd`;
|
|
- lokale vendor-downloads uit de datamap;
|
|
- gecompileerde output;
|
|
- editorback-ups;
|
|
- wachtwoorden, tokens of productiedata.
|
|
|
|
## Database-evolutie
|
|
|
|
Voor iedere schemawijziging komt een nieuwe migratie aan het einde van de keten. Test zowel een lege database als een upgrade vanaf de vorige release. Een migratie moet de applicatie-invarianten herstellen voordat zij haar versienummer registreert.
|
|
|
|
Maak vóór een niet-triviale productiemigratie een PostgreSQL-back-up en noteer de herstelprocedure. Omdat inhoud, historie en bijlagen in PostgreSQL staan, is alleen een kopie van de pakketmap geen inhoudsback-up.
|
|
|
|
## Frontend-evolutie
|
|
|
|
Vendorbibliotheken zijn vastgepind. Een upgrade van EasyMDE, DOMPurify, highlight.js, diff2html, Lucide of de CMapbasis is een functionele wijziging en vereist gerichte smokechecks. Controleer vooral Markdownpariteit tussen preview, leesweergave en historie, en CMapselectie/hit-testing na een grafische update.
|
|
|
|
Wanneer browsercode in ES-modules wordt gesplitst, moeten setup, statische routes, cachegedrag en versiecontrole als één wijziging worden behandeld.
|
|
|
|
## Architectuurbesluiten
|
|
|
|
Leg een besluit op de relevante architectuurpagina vast wanneer het één van deze zaken verandert:
|
|
|
|
- proces- of deploymentstructuur;
|
|
- modulegrens of afhankelijkheidsrichting;
|
|
- database-invariant of versieformaat;
|
|
- vertrouwensgrens of beveiligingsstandaard;
|
|
- teststrategie;
|
|
- schaalverwachting of bewaarbeleid.
|
|
|
|
Een afzonderlijk zwaar ADR-systeem is nu niet nodig. Een compacte sectie met context, keuze, gevolgen en eventuele terugweg op de betrokken pagina is voldoende.
|
|
|
|
## Periodieke controle
|
|
|
|
Controleer bij enkele releases of de documentatie nog overeenkomt met modulelijst, tabellen, routes en actuele knelpunten. Verwijder achterhaalde risico's wanneer zij aantoonbaar zijn opgelost en voeg geen toekomstige componenten als huidige architectuur toe.
|
|
|
|
De overzichtspagina [Architectuur van racket-wiki](racket-wiki:architectuur) blijft het ingangspunt. [Onderhoudbaarheid](racket-wiki:onderhoudbaarheid) bepaalt wanneer documentatie bij een codewijziging hoort; [Verwachte performance](racket-wiki:performance) bepaalt dat schaalmaatregelen op metingen moeten volgen.
|