Samenwerken in Archi op GitHub

Om samen te werken in Archi is een Git-repository nodig en dient de plugin CoArchi in Archi geïnstalleerd te zijn.

Git[bewerken]

Git is een versiebeheersysteem waarmee je wijzigingen in bestanden – zoals architectuurmodellen of documentatie – gestructureerd kunt bijhouden, vergelijken en terugdraaien. Het ondersteunt samenwerking doordat meerdere mensen parallel kunnen werken, zonder elkaars werk te overschrijven.

Git is gestandaardiseerd, het maakt eigenlijk niet uit welke provider je kiest. Het git gedeelte is overal hetzelfde. Wel zijn er verschillen tussen bijvoorbeeld GitHub of GitLab in hoe de site werkt en hoe je met mensen naast git kunt communiceren en samenwerken.

Kies de provider die je fijn vind werken, je kunt een repository altijd verplaatsen naar een andere provider. In de uitleg hieronder wordt GitHub gebruikt.

Inrichten van Git[bewerken]

Er zijn verschillende manieren hoe je kan omgaan met Git. Zo heeft de GEMMA haar repository ingericht volgens het A successful Git branching model. Daarin wordt gebruik gemaakt van de volgende baranches:

master, bevat de gepubliceerde stabiele releases
- dit is de hoofdbranch, die iedere repository heeft
- releases worden vanuit de master-branch uitgevoerd nadat alle relevante wijzigingen uit de develop branch zijn gemerged
develop, bevat de meest actuele opgeleverde nieuwe onderdelen.
- hiervandaan worden feature branches aangemaakt.
- als een feature is afgerond, wordt deze weer in de develop-branch gemerged
feature branches; voor grote wijzigingen op het model wordt een feature branche gemaakt
- de naam van een feature branches refereert aan wat gemaakt wordt. Bijvoorbeeld de feature "Impactanalyse BRK" of "WOO"

Voordelen van deze werkwijze is dat releases gecontroleerd samengesteld kunnen worden door de 'maintainers' van de master branche. Ondertussen kunnen architecten onafhankelijk van de release-cycle werken aan features. Zodra een feature af is wordt deze gemerged met de develop branche om te worden opgenomen in een volgende release.

Inloggen bij GitHub met Archi[bewerken]

Als je met de browser naar GitHub gaat, dan log je in met een username & password (en voor enkele acties nog een extra passcode). Echter als je met een tool - zoals Archi - met een git repository wilt werken, wordt het werken met een Personal Acces Token(PAT-key) geadviseerd.

PAT-keys zijn een alternatief voor het gebruik van wachtwoorden voor verificatie aan GitHub bij gebruik van de GitHub API of de command line. Het Aanmaken van een PAT-Key (Personal Access Token) op GitHub doe je als volgt:

Log in op je GitHub account
Klik op je avatar/icoon rechtsboven en selecteer "Settings".
Scroll in het menu links helemaal naar beneden naar "<> Developer settings"
Selecteer in het linker menu Personal access tokens (classic)
Klik op Generate new token en kies daar de classic variant "Personal access tokens (classic)"
Geef je PAT-Key een duidelijke naam en selecteer alle opties. Vergeet niet de expiratie op de gewenste periode te zetten.
Klik daarna op "Generate token"
Kopieer je PAT-key en bewaar deze goed (bijvoorbeeld in een wachtwoord-manager)

Ophalen model[bewerken]

Om te kunnen samenwerken aan architectuurmodellen dient het model opgehaald te worden in Archi. Dit doe je 'via de volgende handelingen:

Open het menu-item Collaboration
Klik op Import Remote Model to Workspace
Er opent een venster waar gevraagd wordt om het volgende in te vullen:
- URL: Dit is de URL naar de Git-repository. In GitHub is deze bijvoorbeeld te vinden onder de groene knop "Code" in de repository. De URL ziet er als volgt uit:https://github.com/Organisatienaam/repositorynaam.git
- Username: Laat deze leeg.
- Password: Voer hier je aangemaakte PAT-key in.
Daarna opent zich een "Progressing Information" venster.
In de "Collaboration Workspace" worden alle geladen modellen getoond. Dubbelklik op het model wat je wilt openen. Zie je de "Collaboration Workspace" niet, dan kan je deze via het menu Collaboration > Toggle Collaboration Workspace tonen.

Op https://github.com/archimatetool/archi-modelrepository-plugin/wiki/Troubleshooting-Connection-Issues vind je de meeste voorkomende problemen wanneer je het model niet kan ophalen of bewerken.

Wijzigingen naar GitHub doorzetten =[bewerken]

Nadat je wijzigingen hebt doorgevoerd in het model wat je hebt opgehaald en lokaal hebt bewerkt, wil je deze waarschijnlijk ook op GitHub doorvoeren. Het doorvoeren van een wijziging gebeurt in twee stappen:

Committen: hiermee sla je je lokale wijzigingen op in de geschiedenis van het model, zonder deze nog te delen met anderen. Geef altijd in de commit aan welke wijzigingen je hebt doorgevoerd.
Publishen: hiermee stuur je je gecommitteerde wijzigingen naar de gedeelde Git-omgeving, zodat anderen ze ook zien. Hiervoor is eerst een commit nodig. Wanneer je published zonder een commit uitgevoerd te hebben, dan vraagt Archi daarom.