Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Vedlikeholde UML-diagrammer som tekstfiler med kommandolinjeverktøy for PNG-omforming #76

Closed
petterreinholdtsen opened this Issue Mar 7, 2019 · 9 comments

Comments

Projects
None yet
3 participants
@petterreinholdtsen
Copy link
Collaborator

commented Mar 7, 2019

Dette er mangelmelding sendt inn til Arkivverket, se også https://github.com/petterreinholdtsen/noark5-tester/blob/master/mangelmelding/sendt/2019-03-07-uml-format.md .


       Prosjekt  Noark 5 Tjenestegresesnitt
       Kategori  Versjon 1.0 beta
    Alvorlighet  kommentar
   Meldingstype  trenger klargjøring
Brukerreferanse  pere@hungry.com
    Dokumentdel  n/a
     Sidenummer  n/a
    Linjenummer  n/a
Innsendingsdato  2019-03-07

Denne teksten er del av en samling innspill til Noark5-standarden tilgjengelig fra https://github.com/petterreinholdtsen/noark5-tester/.

Beskrivelse

I dag finnes UML-diagrammene i spesifikasjonen som bilder. Det gjør vedlikehold og oppdatering vanskelig og gjør det umulig å bruke git til å se hva som er endret i dem over tid.

Et bedre opplegg vil være å vedlikeholde UML-diagrammene som tekstfiler som automatisk omformes til bilder. Det er en stor fordel om det finnes et fri programvare-kommandolinjeverktøy som kan omforme tekstfilene til bilder som kan vises frem i spesifikasjonen.

Det finnes flere kandidater til verktøy som kan gjøre dette for oss. Se https://modeling-languages.com/text-uml-tools-complete-list/ for en liste.

Har testet endel av dem, og PlantUML ser ut til å være et bra alternativ for vedlikehold av UML-diagrammer. Nettsiden http://plantuml.com/class-diagram har mer informasjon om formatet.

Her er et eksempel på hvordan UML-diagram fra kapittel 7 merket "LoggingOgSporing - (diagram)" kan se ut i PlantUML-format:

@startuml
class Endringslogg {
  systemID : SystemID [0..1]
  referanseArkivenhet : SystemID [0..1] 
  referanseMetadata : string [0..1]
  endretDato : datetime
  endretAv : string
  referanseEndretAv : string
  tidligereVerdi : string [0..1]
  nyVerdi : string [0..1]
}
@enduml

Her er et enklere eksempler fra delen om Kodelister i kapittel 7, figuren merket "Metadata - (diagram)" som PlantUML:

@startuml
class SystemID << simple >>
class BasicTypes::string << simple >>
BasicTypes::string <|-- SystemID
@enduml

Til slutt et mer komplekst eksempel figuren merket "Sakarkiv - (diagram)" i delen om Sakarkiv i kapittel 7:

@startuml uml-sakarkiv-entiteter.puml
Arkivstruktur::Registrering <|-- Arkivstruktur::Basisregistrering
Arkivstruktur::Basisregistrering <|-- Journalpost
Arkivstruktur::Mappe <|-- Saksmappe

Arkivstruktur::Mappe "+mappe 0..1" *--> "+registrering 0..*" Arkivstruktur::Registrering
Arkivstruktur::Mappe *--> "+undermappe 0..*" Arkivstruktur::Mappe

Saksmappe *--> "+sakspart 0..*" Sakspart
Saksmappe "+sak 0..*" o--> "+presedens 0..*" Presedens
Presedens "+presedens 0..*" <--o "+journalpost 0..*" Journalpost

Journalpost *--> "+korrespondansepart 0..*" Korrespondansepart
Journalpost *--> "+avskrivning 0..*" Avskrivning
Journalpost *--> "+dokumentflyt 0..*" Dokumentflyt

Arkivstruktur::Registrering "+registrering 1..*" *--> "+dokumentbeskrivelse 0..*" Arkivstruktur::Dokumentbeskrivelse
@enduml

For denne siste er jeg i tvil om jeg har modellert riktig, da originalfiguren har aggregeringslenker med pil begge veier, og det er en relasjon jeg ikke har funnet i beskrivelser av UML og ikke helt forstår hva betyr.

Ønsket endring

Velg et fri programvarebasert tekstformat for vedlikeholde UML-diagrammer fremover. Jeg anbefaler PlantUML-format, men er åpen for bedre alternativer hvis det finnes. Deretter må alle dagens UML-diagrammer omformes til ønsket format. Deretter må det lages byggeregler for å lage PNG eller SVG-utgaver automatisk fra tekstfilene for bruk i web- og PDF-utgave av spesifikasjonen.

Jeg kan bidra med omforming og justering av byggeregler.

@petterreinholdtsen

This comment has been minimized.

Copy link
Collaborator Author

commented Mar 19, 2019

I og med at ingen har kommentert eller protestert, så tok jeg like godt å startet på en git-gren med omformede UML-diagrammer. Resultatet ligger på https://github.com/petterreinholdtsen/noark5-tjenestegrensesnitt-standard/tree/issue-76-plantuml-diagrams og er ikke ferdig. Når alle er omformet så skal jeg sende inn en endringsforespørsel.

@petterreinholdtsen

This comment has been minimized.

Copy link
Collaborator Author

commented Mar 23, 2019

Første utkast til PlantUML-filer for klassediagrammer er i git (mangler fire pakke-relaterte), og PNG-utgave av EMF og PlantUML-filene er tilgjengelig en kort stund på http://people.skolelinux.org/pere/noark5ts-uml/ for gjennomsyn. Har ikke gode verktøy for å omforme EMF til PNG, så de bildene ser ikke bra ut. Sammenligningen er dermed ikke rettferdig.

@tsodring

This comment has been minimized.

Copy link

commented Mar 24, 2019

Flott jobbet Petter! Vil gjerne se om jeg kan bruke noe av dette til undervisning! Har du tanker på en CC lisens til de? RA / arkitektum har vel noe (C) på de opprinnelige men jeg mener RA har sagt at det de har gjort kan fritt brukes. Hadde vært fint med en avklaring slik at jeg vet jeg kan fritt bruke det på OsloMet. Ellers flott at de er tekstbasert og enkelt å videreutvikle!

@petterreinholdtsen

This comment has been minimized.

Copy link
Collaborator Author

commented Mar 24, 2019

@petterreinholdtsen

This comment has been minimized.

Copy link
Collaborator Author

commented Mar 24, 2019

Mens jeg har holdt på med UML-modelleringen har jeg funnet både små og store feil i dagens UML-skjema. Det er endel skrivefeil i feltnavn. Jeg tenkte å ta tak i disse etter at format for UML-diagrammer er valgt, slik at jeg slipper å måtte gjøre jobben dobbelt. Det hadde dermed vært fint om det raskt kom en avgjørelse om hvordan UML-diagrammer i spesifikasjonen skal vedlikeholdes fremover.

Kan det forresten være en ide å lage et UML-diagram pr. klasse som tas med når klassen beskrives? Det vil være forholdsvis enkelt å lage med PlantUML-opplegget jeg har skrevet, der enkeltklasser er "include-filer" som hentes inn i mer komplekse skjema. Det sikrer både at en klasse er beskrevet på samme måte over alt hvor den brukes, og at vi kan fikse skrivefeil i en klasse ved å kun oppdatere ett sted.

@petterreinholdtsen

This comment has been minimized.

Copy link
Collaborator Author

commented Mar 25, 2019

Jeg publiserte nettopp en bloggpost om bruken av PlantUML for å lage UML-diagrammer for tjenestegrensesnittet. Det kan være en nyttig start hvis du ikke har vært borte i PlantUML før.

petterreinholdtsen added a commit to petterreinholdtsen/noark5-tjenestegrensesnitt-standard that referenced this issue Mar 25, 2019

Redrew all UML diagrams using PlantUML for easier maintenance.
This allow us to track changes in the UML diagrams using git,
and thanks to the use of include files, consistent class
definitions across UML diagrams.

This further make it possible to generate the UML diagram
images automatically from the source files using a command
line free software tool, avoiding the need to accept a non
free software license to be able to correct the UML diagrams.

Fixes arkivverket#76
@hanber

This comment has been minimized.

Copy link
Collaborator

commented Mar 26, 2019

Dette høres ut som en god idé, Bruk PlantUML.

@petterreinholdtsen

This comment has been minimized.

Copy link
Collaborator Author

commented Mar 26, 2019

Ypperlig. Hvor nøye bør PlantUML-filene korrekturleses før de tas i bruk? Eller for å si det på en annen måte, hvor mange korrekturlesere og korrekturlesingsrunder bør det legges opp til?

Jeg mangler gode fri programvareverktøy for å lage gode bilder av EMF-filer, slik at nettsiden jeg laget for å sammenligne ikke gir et rettvisende bilde av originalen. Jeg har brukt 'lodraw' fra LibreOffice til å se på originalen mens jeg modellerte, men når jeg ber samme verktøy lage PNG blir resultatet ikke bra.

Jeg har korrekturlest alle diagrammene minst en gang etter modellering, men mistenker det fortsatt finnes en og annen skrivefeil. Fant for eksempel en i dag med manglende klasse->klasse-lenke i uml-arkivstruktur-attributter.puml. Jeg mistenker det trengs friske øyne for å finne flere feil ved korrekturlesing.

Jeg har oppdatert http://people.skolelinux.org/pere/noark5ts-uml/ med de siste diagrammene. Alle er modellert, og det er kun et spørsmål om mengde kvalitetskontroll før de er klare til å tas inn i spesifikasjonen.

@petterreinholdtsen petterreinholdtsen self-assigned this Mar 26, 2019

petterreinholdtsen added a commit to petterreinholdtsen/noark5-tjenestegrensesnitt-standard that referenced this issue Mar 28, 2019

Redrew all UML diagrams using PlantUML for easier maintenance.
This allow us to track changes in the UML diagrams using git,
and thanks to the use of include files, consistent class
definitions across UML diagrams.

This further make it possible to generate the UML diagram
images automatically from the source files using a command
line free software tool, avoiding the need to accept a non
free software license to be able to correct the UML diagrams.

Fixes arkivverket#76

petterreinholdtsen added a commit to petterreinholdtsen/noark5-tjenestegrensesnitt-standard that referenced this issue Mar 28, 2019

Redrew all UML diagrams using PlantUML for easier maintenance.
This allow us to track changes in the UML diagrams using git,
and thanks to the use of include files, consistent class
definitions across UML diagrams.

This further make it possible to generate the UML diagram
images automatically from the source files using a command
line free software tool, avoiding the need to accept a non
free software license to be able to correct the UML diagrams.

Fixes arkivverket#76

petterreinholdtsen added a commit to petterreinholdtsen/noark5-tjenestegrensesnitt-standard that referenced this issue Mar 29, 2019

Redrew all UML diagrams using PlantUML for easier maintenance.
This allow us to track changes in the UML diagrams using git,
and thanks to the use of include files, consistent class
definitions across UML diagrams.

This further make it possible to generate the UML diagram
images automatically from the source files using a command
line free software tool, avoiding the need to accept a non
free software license to be able to correct the UML diagrams.

Fixes arkivverket#76

petterreinholdtsen added a commit to petterreinholdtsen/noark5-tjenestegrensesnitt-standard that referenced this issue Mar 29, 2019

Added text2uml tool to generate PlantUML diagram from the text in cha…
…pter 7.

This extracts class names, types, inheritence, relations and attributes
from the class definitions in chapter 7, and generate iuml and puml
files to get a UML model of the entire data structure.  It allow us
to more easily find bugs in the model, and to maintain the PlantUML
include files (see issue arkivverket#76) using the textual description.

The relation links need to be verified, as there were some of them
I was unsure how to best model in PlantUML.
@petterreinholdtsen

This comment has been minimized.

Copy link
Collaborator Author

commented Apr 3, 2019

Det hadde vært veldig fint om denne endringen kom inn i master raskt, da den gjør det mulig å sende inn endringsforslag som korrigerer alle defektene i uml-diagrammer, og jeg har avventet å lage konkrete endringsforslag for en rekke mangelmeldinger da jeg ikke får endret EMF-diagrammene.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.