Biblioteksudvikling

Jeg vil tage udgangspunkt i mit test bibliotek, LogSink, som jeg har brugt som prøveklud, til denne side. Biblioteket er i sig selv ikke noget at råbe hurra for, men hele setuppet omkring biblioteket er lavet, så man kan finde inspiration, eller blot overføre 1:1 til sit eget. Servitr.LogSink består af følgende:

1. To nuget feeds (en beta test feed, og en stable feed)
2. En dokumentationsside som kan forklare slutbrugeren om installering, tips og tricks og give en "getting started"
3. Offentlig tilgængelig release pipeline
4. Koden er open source og frit tilgængelig

Da jeg bruger Azure DevOps har jeg sat det hele op i en yaml fil, som kan findes her. Key take aways er:

1. Exclude master, og byg kun master hvis master bliver tagget (tagget bruges af gitversion til at udregne versionsnummeret til nuget pakken)
2. Brug gitversion til at udregne versionsnummeret
3. Brug to feeds: en til beta pakker, og en til stable pakker
4. Byg en nuget pakke pr projekt, hvis du laver .NET Core udvikling. Det er sådan toolingen virker. I "gamle" dage med .NET frameworket, kunne man via nuspec filen bygge et enkel pakke udfra flere projekter, dog er det ikke fuldt understøttet endnu i .NET Core

Overstående får du med hvis kopierer pipeline filen over i dit eget projekt. Husk blot at installere gitversion task'en fra DevOps marketplace, og du er kørende.

Jeg overvejede at bygge to versioner af biblioteket hver gang:

1. et sæt af pakker som indeholder versionsnummeret + prereelase tag (fx 1.0.0-beta0001), og
2. et sæt af pakker som indeholder kun versionnumeret (fx 1.0.0)

Overstående er noget som nogen gør, så man kan release det byg til ens interne beta feed, hvis det viser sig stable nok, dog har jeg valgt at man i stedet skal merge ned og tagget releaset, som så bygger igen. Normalt er jeg fan af at man bygger så få gange som muligt, men jeg kunne godt forstille mig at man

1. laver et beta release
2. tester, og fikser nogle bugs, hvis alt derefter er stable, så
3. laver man dokumentationsopdatering, og en release fil

Da man nok 9/10 gange skal fikse enkelte bugs, opdatere dokumentation osv, så vil jeg hellere at man bygger det igen, i stedet for at lave scripts som kopierer filer ind i den byggede nuget pakke, ændrer versionsnumre etc. Det er ikke gennemskueligt. Læg så dertil at hvis man gerne vil lave md5 kalkulering, så skal denne også opdateres, hvis man manuelt tilføjer filer, før man releaser til ens stable feed.

Man kunne også blot bygge to versioner, som beskrevet i starten, og ikke lave noget inkluderet dokumentation, release fil etc. Men skal man fikse nogle bugs, som man næsten altid skal, så skal man alligevel bygge igen. Jeg har derfor valgt ikke at lave disse scripts, og i stedet for holde det simpelt.

Til versionering bruger jeg GitVersion. Min konfigurationsfil bygger for det meste på default konfigurationen, og er derfor meget simpel (ja jeg har ingen konfigurationsfil, da default konfigurationen bygger på git flow). Vil man køre det hele i fx continous deployment mode, kan man have en gitversion.yml fil som ser således ud:

    assembly-versioning-scheme: MajorMinorPatch
    mode: ContinuousDeployment
    branches: {}
    ignore:
      sha: []
    merge-message-formats: {}

Jeg vil anbefale at man laver et test git repo, installere GitVersion lokalt, læser dokumentationen (læs specielt den del om de forskellige modes) og tester lidt (gitversion kan hjælpe dig igang ved at du kører gitversion init i konsollen). GitVersion kan mange ting. Man kan bumpe versioneringen via commit beskeder, kun incremente versionen på merge, tagge versionsnummeret på master osv osv osv. Alt afhængig af hvad du bygger, skal du bruge de forskellige features.  Jeg valgte forkert i starten.

    dotnet tool install --global GitVersion.Tool
    dotnet gitversion /updateprojectfile

Jeg bruger to dokumentations versioner:

1. readme.md - målgruppen er udviklere og brugere af github
2. en github side - som er underlagt kildekontrol. Målgruppen er brugere af nuget, som gerne vil vide hvordan man kommer igang

Readme filen indeholder links til github siden. Informationen på de to sider er ikke 1:1. De læner sig meget opad hianden. Havde jeg gjort ekstra meget ud af det, ville readme filen forklare endnu mere om hvad der skal til hvis man vil contribute til biblioteket, tekniske detaljer osv. Github siden ville indeholde en "getting started" og nogle eksempler.

Jeg vil anbefale at man forsøger at gøre overstående, så der både er noget til udvikleren, som gerne vil bidrage, og noget til udvikleren, som bare gerne vil bruge.

Jeg vil dog gerne understrege: hold det open source så alle kan modificere, teste, debugge, indmelde issues, og GØRE DET BEDRE. Alle får noget ud af det. Alle hjælper hinanden. Det er godt og gøre verden til et bedre sted.

Vil du gerne selv igang, så brug:

1. Min gitversion fil
2. Min pipeline fil - såfremt du bruger Azure DevOps

Derved får du versionering, og hele din release pipeline. Du er hurtig igang (det eneste du skal er at sætte et library op i Azure DevOps, og et beta feed). Om du skal bruge git flow eller github flow (eller en helt tredje), en eller flere nuget pakker eller opdatere pipeline filen, så den laver to versioner (en med prerelease tag og en uden), er helt op til dig.

Du kan selvfølgelig kun bruge pipeline filen, hvis du bruger Azure DevOps. Jeg vil også anbefale dig at smide koden et sted som fx Github. Bruger du Github, så lav en github side som præsenterer brugseksempler, installationsvejledninger og hvor man kan finde mere information (fx github repo'et).

1. hold det open source
2. lav dokumentation, gerne opdelt: en til udvikleren som vil udvide, og en til slutbrugeren, som bare gerne vil bruge
3. brug gitversion
4. lav to feeds: en beta feed, og en stable feed (om det er nuget feed til nuget pakker, eller en FTP download til exe filer er såvidt ligemeget)