blog/archive/2019/03/03.rss

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <rss version='2.0' xmlns:lj='http://www.livejournal.org/rss/lj/1.0/'>
   3         <channel>
   4                 <title>Petter Reinholdtsen - Entries from March 2019</title>
   5                 <description>Entries from March 2019</description>
   6                 <link>http://people.skolelinux.org/pere/blog/</link>
   7
   8
   9         <item>
  10                 <title>Åpen og gjennomsiktig vedlikehold av spesifikasjonen for Noark 5 Tjenestegrensesnitt</title>
  11                 <link>http://people.skolelinux.org/pere/blog/_pen_og_gjennomsiktig_vedlikehold_av_spesifikasjonen_for_Noark_5_Tjenestegrensesnitt.html</link>
  12                 <guid isPermaLink="true">http://people.skolelinux.org/pere/blog/_pen_og_gjennomsiktig_vedlikehold_av_spesifikasjonen_for_Noark_5_Tjenestegrensesnitt.html</guid>
  13                 <pubDate>Mon, 11 Mar 2019 16:00:00 +0100</pubDate>
  14                 <description>&lt;p&gt;Et virksomhetsarkiv for meg, er et arbeidsverktøy der en enkelt kan
  15 finne informasjonen en trenger når en trenger det, og der
  16 virksomhetens samlede kunnskap er tilgjengelig. Det må være greit å
  17 finne frem i, litt som en bibliotek. Men der et bibliotek gjerne tar
  18 vare på offentliggjort informasjon som er tilgjengelig flere steder,
  19 tar et arkiv vare på virksomhetsintern og til tider personlig
  20 informasjon som ofte kun er tilgjengelig fra et sted.&lt;/p&gt;
  21
  22 &lt;p&gt;Jeg mistenker den eneste måten å sikre at arkivet inneholder den
  23 samlede kunnskapen i en virksomhet, er å bruke det som virksomhetens
  24 kunnskapslager. Det innebærer å automatisk kopiere (brev, epost,
  25 SMS-er etc) inn i arkivet når de sendes og mottas, og der filtrere
  26 vekk det en ikke vil ta vare på, og legge på metadata om det som er
  27 samlet inn for enkel gjenfinning. En slik bruk av arkivet innebærer at
  28 arkivet er en del av daglig virke, ikke at det er siste hvilested for
  29 informasjon ingen lenger har daglig bruk for. For å kunne være en del
  30 av det daglige virket må arkivet enkelt kunne integreres med andre
  31 systemer.  I disse dager betyr det å tilby arkivet som en
  32 nett-tjeneste til hele virksomheten, tilgjengelig for både mennesker
  33 og datamaskiner.  Det betyr i tur å både tilby nettsider og et
  34 maskinlesbart grensesnitt.&lt;/p&gt;
  35
  36 &lt;p&gt;For noen år siden erkjente visjonære arkivarer fordelene med et
  37 standardisert maskinlesbart grensesnitt til organisasjonens arkiv.  De
  38 gikk igang med å lage noe de kalte
  39 &lt;a href=&quot;https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/&quot;&gt;Noark
  40 5 Tjenestegrensesnitt&lt;/a&gt;.  Gjort riktig, så åpner slike maskinlesbare
  41 grensesnitt for samvirke på tvers av uavhengige programvaresystemer.
  42 Gjort feil, vil det blokkere for samvirke og bidra til
  43 leverandørinnlåsing.  For å gjøre det riktig så må grensesnittet være
  44 klart og entydig beskrevet i en spesifikasjon som gjør at
  45 spesifikasjonen tolkes på samme måte uavhengig av hvem som leser den,
  46 og uavhengig av hvem som tar den i bruk.&lt;/p&gt;
  47
  48 &lt;p&gt;For å oppnå klare og entydige beskrivelser i en spesifikasjon, som
  49 trengs for å kunne få en fri og åpen standard (se
  50 &lt;a href=&quot;http://people.skolelinux.org/pere/blog/Fri_og__pen_standard__slik_Digistan_ser_det.html&quot;&gt;Digistan-definisjon&lt;/a&gt;),
  51 så trengs det en åpen og gjennomsiktig inngangsport med lav terskel,
  52 der de som forsøker å ta den i bruk enkelt kan få inn korreksjoner,
  53 etterlyse klargjøringer og rapportere uklarheter i spesifikasjonen.
  54 En trenger også automatiserte datasystemer som måler og sjekker at et
  55 gitt grensesnitt fungerer i tråd med spesifikasjonen.&lt;/p&gt;
  56
  57 &lt;p&gt;For Noark 5 Tjenestegrensesnittet er det nå etablert en slik åpen
  58 og gjennomsiktig inngangsport på prosjekttjenesten github.  Denne
  59 inngangsporten består først og fremst av en åpen portal som lar enhver
  60 se hva som er gjort av endringer i spesifikasjonsteksten over tid, men
  61 det hører også med et åpent &amp;quot;diskusjonsforum&amp;quot; der en kan
  62 komme med endringsforslag og forespørsler om klargjøringer.  Alle
  63 registrerte brukere på github kan bidra med innspill til disse
  64 henvendelsene.&lt;/p&gt;
  65
  66 &lt;p&gt;I samarbeide med Arkivverket har jeg fått opprettet et git-depot
  67 med spesifikasjonsteksten for tjenestegrensesnittet, der det er lagt
  68 inn historikk for endringer i teksten de siste årene, samt lagt inn
  69 endringsforslag og forespørsler om klargjøring av teksten.  Bakgrunnen
  70 for at jeg bidro med dette er at jeg er involvert i
  71 &lt;a href=&quot;https://gitlab.com/OsloMet-ABI/nikita-noark5-core&quot;&gt;Nikita-prosjektet&lt;/a&gt;,
  72 som lager en fri programvare-utgave av Noark 5 Tjenestegrensesnitt.
  73 Det er først når en forsøker å lage noe i tråd med en spesifikasjon at
  74 en oppdager hvor mange detaljer som må beskrives i spesifikasjonen for
  75 å sikre samhandling.&lt;/p&gt;
  76
  77 &lt;p&gt;Spesifikasjonen vedlikeholdes i et rent tekstformat, for å ha et
  78 format egnet for versjonskontroll via versjontrollsystemet git.  Dette
  79 gjør det både enkelt å se konkret hvilke endringer som er gjort når,
  80 samt gjør det praktisk mulig for enhver med github-konto å sende inn
  81 endringsforslag med formuleringer til spesifikasjonsteksten.  Dette
  82 tekstformatet vises frem som nettsider på github, slik at en ikke
  83 trenger spesielle verktøy for å se på siste utgave av
  84 spesifikasjonen.&lt;/p&gt;
  85
  86 &lt;p&gt;Fra dette rene tekstformatet kan det så avledes ulike formater, som
  87 HTML for websider, PDF for utskrift på papir og ePub for lesing med
  88 ebokleser.  Avlednings-systemet (byggesystemet) bruker i dag
  89 verktøyene pandoc, latex, docbook-xsl og GNU make til
  90 transformasjonen.  Tekstformatet som brukes dag er
  91 &lt;a href=&quot;https://www.markdownguide.org/&quot;&gt;Markdown&lt;/a&gt;, men det vurderes
  92 å
  93 &lt;a href=&quot;https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/issues/9&quot;&gt;endre
  94 til formatet RST&lt;/a&gt; i fremtiden for bedre styring av utseende på
  95 PDF-utgaven.&lt;/p&gt;
  96
  97 &lt;p&gt;Versjonskontrollsystemet git ble valgt da det er både fleksibelt,
  98 avansert og enkelt å ta i bruk. Github ble valgt (foran f.eks. Gitlab
  99 som vi bruker i Nikita), da Arkivverket allerede hadde tatt i bruk
 100 Github i andre sammenhenger.&lt;/p&gt;
 101
 102 &lt;p&gt;Enkle endringer i teksten kan gjøres av priviligerte brukere
 103 direkte i nettsidene til Github, ved å finne aktuell fil som skal
 104 endres (f.eks. kapitler/03-konformitet.md), klikke på den lille
 105 bokstaven i høyre hjørne over teksten. Det kommer opp en nettside der
 106 en kan endre teksten slik en ønsker. Når en er fornøyd med endringen
 107 så må endringen &amp;quot;sjekkes inn&amp;quot; i historikken. Det gjøres ved
 108 å gi en kort beskrivelse av endringen (beskriv helst hvorfor endringen
 109 trengs, ikke hva som er endret), under overskriften &amp;quot;Commit
 110 changes&amp;quot;. En kan og bør legge inn en lengre forklaring i det
 111 større skrivefeltet, før en velger om endringen skal sendes direkte
 112 til &#39;master&#39;-grenen (dvs. autorativ utgave av spesifikasjonen) eller
 113 om en skal lage en ny gren for denne endringen og opprette en
 114 endringsforespørsel (aka &amp;quot;Pull Request&amp;quot;/PR). Når alt dette
 115 er gjort kan en velge &amp;quot;Commit changes&amp;quot; for å sende inn
 116 endringen. Hvis den er lagt inn i &amp;quot;master&amp;quot;-grenen så er den
 117 en offisiell del av spesifikasjonen med en gang.  Hvis den derimot er
 118 en endringsforespørsel, så legges den inn i
 119 &lt;a href=&quot;https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/pulls&quot;&gt;listen
 120 over forslag til endringer&lt;/a&gt; som venter på korrekturlesing og
 121 godkjenning.&lt;/p&gt;
 122
 123 &lt;p&gt;Større endringer (for eksempel samtidig endringer i flere filer)
 124 gjøres enklest ved å hente ned en kopi av git-depoet lokalt og gjøre
 125 endringene der før endringsforslaget sendes inn. Denne prosessen er
 126 godt beskrivet i dokumentasjon fra github.  Git-prosjektet som skal
 127 &amp;quot;klones&amp;quot; er
 128 &lt;a href=&quot;https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/&quot;&gt;https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/&lt;/a&gt;.&lt;/p&gt;
 129
 130 &lt;p&gt;For å registrere nye utfordringer (issues) eller kommentere på
 131 eksisterende utfordringer benyttes nettsiden
 132 &lt;a href=&quot;https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/issues&quot;&gt;https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/issues&lt;/a&gt;.
 133 I skrivende stund er det 48 åpne og 11 avsluttede utfordringer.  Et
 134 forslag til hva som bør være med når en beskriver en utfordring er
 135 tilgjengelig som utfordring
 136 &lt;a href=&quot;https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/issues/14&quot;&gt;#14&lt;/a&gt;.&lt;/p&gt;
 137
 138 &lt;p&gt;For å bygge en PDF-utgave av spesifikasjonen så bruker jeg i dag en
 139 Debian GNU/Linux-maskin med en rekke programpakker installert.  Når
 140 dette er på plass, så holder det å kjøre kommandoen &#39;make pdf html&#39; på
 141 kommandolinjen, vente ca. 20 sekunder, før spesifikasjon.pdf og
 142 spesifikasjon.html ligger klar på disken. Verktøyene for bygging av
 143 PDF, HTML og ePub-utgave er også tilgjengelig på Windows og
 144 MacOSX.&lt;/p&gt;
 145
 146 &lt;p&gt;Github bidrar med rammeverket.  Men for at åpent vedlikehold av
 147 spesifikasjonen skal fungere, så trengs det folk som bidrar med sin
 148 tid og kunnskap.  Arkivverket har sagt de skal bidra med innspill og
 149 godkjenne forslag til endringer, men det blir størst suksess hvis alle
 150 som bruker og lager systemer basert på Noark 5 Tjenestegrensesnitt
 151 bidrar med sin kunnskap og kommer med forslag til forebedringer.  Jeg
 152 stiller.  Blir du med?&lt;/p&gt;
 153
 154 &lt;p&gt;Det er viktig å legge til rette for åpen diskusjon blant alle
 155 interesserte, som ikke krever at en må godta lange kontrakter med
 156 vilkår for deltagelse. Inntil Arkivverket dukker opp på IRC har vi
 157 laget en IRC-kanal der interesserte enkelt kan orientere seg og
 158 diskutere tjenestegrensesnittet. Alle er velkommen til å ta turen
 159 innom
 160 &lt;a href=&quot;https://webchat.freenode.net/?channels=nikita&quot;&gt;#nikita&lt;/a&gt;
 161 (f.eks. via irc.freenode.net) for å møte likesinnede.&lt;/p&gt;
 162
 163 &lt;p&gt;Det holder dog ikke å ha en god spesifikasjon, hvis ikke de som tar
 164 den i bruk gjør en like god jobb. For å automatisk teste om et konkret
 165 tjenestegrensesnitt følger (min) forståelse av
 166 spesifikasjonsdokumentet, har jeg skrevet et program som kobler seg
 167 opp til et Noark 5v4 REST-tjeneste og tester alt den finner for å se
 168 om det er i henhold til min tolkning av spesifikasjonen.  Dette
 169 verktøyet er tilgjengelig fra
 170 &lt;a href=&quot;https://github.com/petterreinholdtsen/noark5-tester&quot;&gt;https://github.com/petterreinholdtsen/noark5-tester&lt;/a&gt;,
 171 og brukes daglig mens vi utvikler Nikita for å sikre at vi ikke
 172 introduserer nye feil.  Hvis en skal sikre samvirke på tvers av ulike
 173 systemer er det helt essensielt å kunne raskt og automatisk sjekke at
 174 tjenestegrensesnittet oppfører seg som forventet.  Jeg håper andre som
 175 lager sin utgave av tjenestegrensesnittet vi bruke dette verktøyet,
 176 slik at vi tidlig og raskt kan oppdage hvor vi har tolket
 177 spesifikasjonen ulikt, og dermed få et godt grunnlag for å gjøre
 178 spesifikasjonsteksten enda klarere og bedre.&lt;/p&gt;
 179
 180 &lt;p&gt;Dagens beskrivelse av Noark 5 Tjenestegrensesnitt er et svært godt
 181 utgangspunkt for å gjøre virksomhetens arkiv til et dynamisk og
 182 sentralt arbeidsverktøy i organisasjonen.  Blir du med å gjøre den
 183 enda bedre?&lt;/p&gt;
 184 </description>
 185         </item>
 186
 187         </channel>
 188 </rss>