Innehåll

Revisionshistorik

Inledning

Dokumentet beskriver den metodik som openEHR Sverige följer i sitt arbete med GitHub. Dokumentet är

• Styrande för personer som arbetar med GitHub inom ramen för arbetet i openEHR Sverige och

• Rekommenderat för personer som arbetar med openEHR i GitHub hos en annan aktör, såsom en region, systemleverantör.

Nyttoeffekter

Genom att följa denna instruktion uppnås följande nyttoeffekter:

• Alla gör lika

• Arbetsprocedurer blir tydligare

• Github-material hålls välstädat

• Gör det möjligt för nya personer att snabbare sätta sig in i arbete med GitHub inom ramen för openEHR

• Över tid kommer det enhetliga sättet att använda GitHub som strategi bidra till att höja kunskapsnivån inom openEHR Sverige och de aktörer som följer instruktionen

Terminologi och befintligt material

GitHub-terminologi

Nedan listas termer som är relevanta inom GitHub och därmed för förståelsen av instruktionen.

Clinical Knowledge Manager (CKM)-terminologi

Nedan listas termer som är relevanta inom CKM:en.

Term	Beskrivning	Länk till mer information

Term	Beskrivning	Länk till mer information
Clinical Knowledge Manager (CKM)	CKM:en är ett system för gemensam utveckling, förvaltning och publicering av ett brett utbud av kliniska kunskapsresurser. Resurserna omfattar bl.a. arketyper och templates.	Clinical Knowledge Manager (openehr.org)
Brancher i CKM	CKM:en stödjer branches. Till skillnad från Git baseras CKM:en på ett centralt versionshanteringssystem. Branchen/Brancherna för en resurs nås genom att välja resursen (t.ex. arketypen Anatomical location) välja fliken “Archetype history” välja “Published Only” för att endast se branchen CKM Trunk eller “All revisions” för att se alla brancherna. Open   Brancherna i CKM:en har ingenting att göra med brancherna i GitHub!
CKM Trunk	CKM Trunk är huvudbranchen i CKM:en.

Befintliga repositoryn, forkar, GitHub-organisationer och -teams

Nedan listas information om befintliga repositoryn, forkar, GitHub-organisationer och -teams som är relevanta.

Open

Anvisningar

Gemensamt nationellt arbete inom openEHR Sverige

Det gemensamma nationella arbete med openEHR-resurser (som arketyper eller templates) som drivs inom openEHR Sverige ska ske i teamet Svenskt arketypsamarbete och de repositoryn som ingår.

Steg: Arbeta i ett repository

Om du ska arbeta med arketyper eller templates som är tänkta att ingå i CKM Mirror, gå till repositoryt modellbibliotek/CKM Mirror. Följ då nedanstående steg:

• Visa befintliga brancher i repositoryt för att kolla om det finns en branch för det området som du vill jobba med

• Skapa en ny branch om det inte finns någon branch för ditt område. Den nya branchen ska skapas från masterbranchen i repositoryt modellbibliotek/CKM Mirror. Inget arbete ska ske direkt i mastern utan i områdesspecifika brancher.

• Koppla GitHub branch till Archetype Designer repository

• Arbeta med arketyperna eller templates t.ex. i Archetype Designer-repositoryt

• Ta bort filer i en branch vid behov

• Committa ändringar till en branch (nya artefakter sparas per default osorterat under mappen local)

Om du tänkte öva på arketyper eller templates som inte är tänkta att ingå i CKM Mirror, gå till Modellbibliotek/Arbetsyta-openEHR. Följ i övrigt ovanstående steg. Nya brancher kan skapas från masterbranchen i repositoryt Modellbibliotek/Arbetsyta-openEHR eller vid behov från andra brancher som finns i repositoryt.

Steg: Hantera uppdaterade artefakter

Ibland uppdateras artefakter, t.ex. arketyper, som du behöver i ditt pågående arbete. För att få in artefakterna i din branch, följ nedanstående steg:

• Be ansvariga inom openEHR Sverige att uppdatera forken modellbibliotek/CKM Mirror, se Uppdatera en fork

• Merga in ändringarna från masterbranchen till din branch

• Kontrollera att de uppdaterade artefakter fungerar ihop med ditt resterande arbete

• Fortsätt arbeta med dina arketyper eller templates

Steg: Wrap up

När arbetet inom din branch är klart, följ nedanstående steg för att avsluta arbetet:

• Presentera arbetet inom openEHR Sverige, få beslut om hur arbetet tas vidare (beror på om arbetet enbart är relevant inom Sverige eller internationellt)

• Om arbetet är relevant inom Sverige

  • openEHR Sverige beslutar om namn för lämplig underbibliotek/mapp, (se Användning av underbibliotek/mappar)

  • Skapa underbibliotek/mapp och flyttar filerna som har skapats dit

  • Merga brancher, dvs. merga branchen du arbetar i till masterbranchen.

  • Ta bort branch som du har arbetat i (vill vi det? vill vi ha kvar historik? hur gör vi det?)

• Om arbetet är relevant internationellt

  • Lägg till artefakten som har skapats i CKM:en

  • Få artefakten granskad

  • När artefakten har godkänts och ändringen från CKM:en har synkats till openEHR/CKM Mirror

    • Ansvarig inom openEHR Sverige uppdaterar forken modellbibliotek/CKM Mirror, se Uppdatera en fork, vilket gör att den nya artefakten ska finnas tillgänglig i masterbranchen under respektive underbibliotek/mapp under “local”, t.ex. om en ny arketyp har skapats kommer den finnas under underbiblioteket/mappen “local/archetype”

    • Ta bort branch som du har arbetat i (vill vi det? vill vi ha kvar historik? hur gör vi det?)

Steg: Uppdatera forken “Modellbibliotek/CKM Mirror”

Forken Modellbibliotek/CKM Mirror ska hållas i synk med uppstream-repository:t openEHR/CKM Mirror. Detta sker idag inte per automatik utan måste göras manuellt. Följ nedanstående steg för att uppdatera forken:

Uppdatera en fork

Namngivning

Användning av underbibliotek/mappar

Beskrivning av mapparna local and remote finns på modellbibliotek/CKM-mirror: openEHR.org CKM mirror (github.com)

Arketyper, resp. templates som tas fram inom openEHR Sverige och som är tänkt för nationell användning ska läggas i en egen underbibliotek/mapp som skapas på samma nivå som local och remote, t.ex. PDL.

Aktörsspecifikt arbete

Detta avsnitt vänder sig till personer som arbetar med openEHR hos en region, systemleverantör eller dylikt och som vill använda GitHub.

Det rekommenderas att arbetet sker i en GitHub-organisation som är speciellt framtagen för den aktuella aktören. Se exemplet på GitHub-organisationen som heter “Region Stockholm” för inspiration i arbetet. I den framtagna GitHub-organisationen för aktören kan det vid behov skapas team för att ytterligare strukturera arbetet. Det rekommenderas dessutom att skapa en fork som är forkat från repositoryt Modellbibliotek/CKM Mirror. Per default innehåller forken en branch som heter “master”. Rekommendationen är att driva det pågående arbetet gällande ett visst område i en separat branch som är tagen från master och som sedan mergas tillbaka till master. Vid behov kan det skapas forkar från andra repositoryn.

Steg: Sätt upp GitHub-yta

Följ nedanstående steg för att komma igång med ditt arbete på GitHub

• Skapa en ny organisation

• Skapa ett nytt team eller flera vid behov

• Skapa en ny fork utifrån repositoryt Modellbibliotek/CKM Mirror och vid behov från andra repositoryn

• Skapa ett nytt repository vid behov för ett fristående repository

Steg: Arbeta i ett repository

Nu har du skapat din egen fork eller ett fristående repository, följ nedanstående steg för att arbeta i/med branchen.

• Skapa en ny branch

• Koppla GitHub branch till Archetype Designer repository

• Arbeta med arketyperna eller templates i Archetype Designer-repositoryt

• Committa ändringar till en branch

• Ta bort filer i en branch vid behov

• Skapa underbibliotek/mapp

• Merga brancher

• Ta bort branch

Steg: Uppdatera forken

Forken som har skapats ska hållas i synk med uppstream-repository:t, t.ex. Modellbibliotek/CKM Mirror. Detta sker idag inte per automatik utan måste göras manuellt. Följ nedanstående steg för att uppdatera forken:

Uppdatera en fork

Namngivning

GitHub-lathundar

Lathundarna är skrivna för GitHub:s användargränssnitt. Respektive aktivitet kan dock även genomföras via kommandotolken.

Skapa ett GitHub-konto

För att skapa ett GitHub-konto, gå till https://github.com/ och följ anvisningarna.

Skapa en ny organisation

Kolla om det finns en GitHub-organisation för den aktören som du tillhör.

Om det inte finns, skapa en ny organisation genom att följa anvisningen på Creating a new organization from scratch - GitHub Docs som är en generell beskrivning på hur man skapa en organisation i GitHub.

• Välj teamplan som passar din organisation (gratisvarianten brukar funka fint)

• Ange information om organisationen, se skärmdump nedan

  • Välj ett namn

  • Ange mejladress till en kontaktperson

  • Välj “A business or institution”

• Lägg till medlemmar i organisationen (medlemmarna behöver ha ett GitHub-konto för att kunna läggas till).

Skapa ett nytt team

Skapa ett nytt team genom att följa anvisningen på Creating a team - GitHub Docs som är en generell beskrivning på hur man skapa ett team i GitHub.

Skapa ett nytt repository

Skapa ett nytt repository genom att följa anvisningen på Creating a new repository - GitHub Docs som är en generell beskrivning på hur man skapa ett repository i GitHub.

När repositoryt är skapat kan man lägga till medlemmar eller team som ska vara med i arbetet kring repositoryt. Detta görs antingen direkt i anslutning till att repositoryt har skapats eller senare genom att gå in till repositoryt, välja “Settings”, välja “Collaborators and teams” och sedan “Add people” eller “Add teams”.

Skapa en ny fork

På Fork a repo - GitHub Docs finns en generell beskrivning på hur man skapa en fork. Nedan följer en beskrivning som är specifik för att skapa en fork från Modellbibliotek/CKM Mirror

• Navigera till Modellbibliotek/CKM Mirror

• Navigera till övre höger hörn, klicka på pilen bredvid “Fork” och välj “Create a new fork”

• Fyll i uppgifterna om forken som ska skapas

  • Ange Owner (t.ex. namn på region eller leverantör som “Region Östergötland” eller “TietoEvry”, krävs att de är tillagda som GitHub organisation, se Skapa en ny organisation )

  • Ange Repository name (dvs. CKM-mirror-via-modellbibliotek)

  • Fyll i en beskrivning av forken under Description

  •  

När ska man forka från master (nationella samarbeten) och när ska man göra det i en lokal fork (lokala projekt)

Synka en fork

Synka en fork genom att följa anvisningen på Syncing a fork - GitHub Docs som är en generell beskrivning på hur man uppdatera en fork i GitHub.

Observera! För att enbart få med uppdateringar från uppstream-repository:t välj “Update branch”.

Visa befintliga brancher

Visa befintliga brancher genom att följa anvisningen på Viewing branches in your repository - GitHub Docs som är en generell beskrivning på hur man visar brancher i GitHub.

Skapa en ny branch

Skapa en ny branch genom att följa anvisningen på Creating and deleting branches within your repository - GitHub Docs som är en generell beskrivning på hur man skapa en branch i GitHub.

Följ anvisningar i Namnge en branch vid namngivning av branchen.

Under “Branch source”, välj vilket repository och vilken branch som den nya branchen ska skapas ifrån. I nedanstående skärmdump skapas den nya branchen “test” från masterbranchen i repositoryt modellbibliotek/CKM Mirror.

Namnge branch

Här listas allmänna rekommendationer för att namnge en branch

• Döp branchen till “xyz” där xyz är en valfri text utan mellanslag som beskriver området som branchen avser

• Använd gemener (små bokstäver)

• Använd engelska (därmed ska inga å, ä eller ö ingå i namnet)

• Om namnet innehåller flera ord bindas de ihop med bindestreck

Exempel på namn är “chemotherapy-symptoms” eller “laboratory-medicine”.

Döpa om en branch

Döpa om en branch genom att följa anvisningen på Renaming a branch - GitHub Docs som är en generell beskrivning på hur man merga brancher i GitHub.

Ta bort filer i en branch

Filer kan tas bort på olika sätt. Nedan förklaras hur man ta bort en fil genom att använda github.dev

Via github.dev

• Öppna filen som du vill ta bort, (nedanstående skrämdumpar är tagna med README-filen som exempelfil)

• När filen har öppnats, klicka på pilen till höger och sedan välj “github.dev”

• Markera filen i hierarkin till vänster och klicka på “Delete” på ditt tangentbord

• Efter att ha klickat “Delete” behöver du bekräfta borttagning genom att klicka “Delete” igen i en pop-up

• När du har tagit bort filen behöver du committa och pusha dina ändringarna till repositoryt (än så länge har alla dina ändringar enbart skett lokalt). Till vänster i menyn kommer det dyka upp en liten 1:a vid gulmarkerade symbolen för Source control. Kicka på symbolen och fyll i ett meddelande som beskriver förändringen som du har gjort. Klicka sedan på “Commit & Push”

•  

Committa ändringar till en branch

Ändringar kan committas på olika sätt. Nedan förklaras hur man committa via Archetype Designer eller direkt via GitHub men det kan finnas flera andra sätt.

Via Archetype Designer

För att committa ändringar via Archetype Designer följ nedanstående steg:

• Öppna arketypen eller templaten som du arbetar med i ditt Archetype Designer-repository (och som är kopplat till en GitHub-branch, se Koppla GitHub branch till Archetype Designer repository .

• Välj “Save”

• Fyll i information i pop-up rutan, inkl. en commit message och välj “Save”, se skärmdump nedan.

Committen kommer synas i branchen i GitHub, se skärmdump nedan.

Via GitHub

Commit via GitHub kan ske på olika sätt. För att committa småändringar via GitHub följ nedanstående steg:

• Gå till branchen där en fil ska ändras

• Gå till filen

• Välj “Edit”

   

Skapa underbibliotek/mapp

Skapa ett underbibliotek/en mapp i en branch i ett repository genom att följa anvisningen i kommentaren på Add a folder · community · Discussion #22534 (github.com).

Merga brancher

Merga två brancher genom att följa anvisningen på Creating and deleting branches within your repository - GitHub Docs som är en generell beskrivning på hur man merga brancher i GitHub.

Ta bort branch

Ta bort en branch genom att följa anvisningen Creating and deleting branches within your repository - GitHub Docs på som är en generell beskrivning på hur man tar bort en branch i GitHub.

Koppla GitHub-branch till Archetype Designer-repository

Följ nedanstående steg för att koppla en GitHub-branch till ett Archetype Designer-repository. Detta behöver göras oavsett om branchen i GitHub är ny eller redan befintlig.

• Logga in till Archetype Designer (openehr.org) (det är fördelaktigt om inloggning sker med ett personligt GitHub-konto)

• Välj “New repository”

• Under “Repository type” välj GitHub

• Under “Repository name” välj ett namn för Archetype Designer-repository:t som speglar vilken GitHub-branchen (-organisationen och -repositoryt) det ska kopplas till.

• Under “Branch” välj GitHub-branchen som ska används, t.ex. den som du har skapat själv.

• Under “Repository” skriv namnet på det repositoryt där GitHub-branchen finns

• Under “Owner” skriv namnet på den GitHub-organisationen som äger repositoryt där GitHub-branchen finns.

Nedanstående skärmdump visar ett exempel där Archetype Designer-repository:t har döpts till “UMI i modellbibliotekets CKM-mirror” och är skapat utifrån branchen “UMI-varning-info” i GitHub-repositoryt Modellbibliotek/CKM Mirror

Gör en release

Fyll på

Säkerhet

Det finns ett antal sätt att säkra sina brancher, resp. repositoryn i GitHub. Nedan finns några förslag:

Skydda en branch

Fyll på

Använd filen CODEOWNERS

Du kan använda en CODEOWNERS-fil för att definiera individer eller team som är ansvariga för kod (eller annat innehåll) i ett repository. “Kodägare” blir automatiskt tillfrågade om granskning när någon öppnar en pull request som ändrar kod som de äger. Följ About code owners - GitHub Docs för att få mer information om vad en CODEOWNERS-fil är, samt hur den skapas.

För ett exempel, se hur det är uppsatt inom Region Stockholm: CKM-mirror-via-modellbibliotek/.github/CODEOWNERS at master · regionstockholm/CKM-mirror-via-modellbibliotek

Användning av brancher i CKM resp. GitHub

• När jobbas mot CKM branches och när mot GitHub branches

  • Översättningar görs på brancher i CKM där det finns bra verktygsstöd inbyggt

  • Annat nationellt och lokalt arbete görs i brancher i Github på lämplig Fork

Övrigt

Härunder samlas tankar som på sikt ska tas upp i ovanstående anvisning

• fixa automatisk uppdatering av Modellbibliotek/CKM Mirror - master, innebär bl.a. följande steg

  • arbetet som pågår sker i brancherna (en del arbete behöver flyttas från master till brancherna)

  • skapa ett Jira-ärende för arbetet som omfattar bl.a. att skapa script och sedan ladda upp scriptet i github

• lägg till exempelflöde för uppdatering av en arketyp och hur man jobbar

• beskriva hur man kan jämföra ändringar två branches i archetype designer

  • kräver egen branch som man jobbar i, tex. in och utfarter - ska finnas som repository i archetype designer

  • kräver att man har tagit ut branchen som man vill jämföra mot som eget repository i archetype designer, t.ex. Modellbibliotek/CKM Mirror - master