Skip to main content

Project: IaC IT-news

Doelstelling​

De beste manier om Git goed in de vingers te krijgen, is er mee aan de slag gaan.

Dat zullen we de komende weken doen aan de hand van een project waar jullie samen aan werken.

Dat project bestaat uit een blog die jullie in groep zullen opzetten. Daar zullen jullie wekelijks artikelen aan toevoegen. Op vrijdag verschijnt telkens een nieuwe editie, met de artikelen die die week gemaakt werden.

Om zo’n site te maken, gebruiken we Docusaurus. Dat is een statische site-generator op basis van Markdown. Zonder het misschien te weten ken je dit al: deze opgave werd namelijk ook gemaakt met Docusaurus.

belangrijk

  • Hoewel we de kwaliteit van de blogberichten ook opnemen in de evaluatie, ligt de focus op het correct gebruik van Git.

  • Verder hechten we ook belang aan het gebruik van de extra tools die webgebaseerde Git-repository platformen bieden om software development projecten uit te werken in teams.

Werkwijze​

We maakten voor deze opgave een aantal groepjes. Die verdeling vind je op een tweede tabblad in het planningsdocument.

De repositories (en gitlab group) worden voor jullie voorzien. Eens de teams verdeeld zijn, voegen we jullie toe als maintainer aan deze repository op gitlab.com.

Deze repositories bevatten momenteel een werkende template. Deze kan je als startpunt gebruiken voor je verdere aanvullingen.

Rolverdeling​

Elke week zullen de rollen gewisseld worden binnen het team. Dat doen we zodat iedereen ervaring kan opdoen met alle taken binnen de vooropgestelde workflow.

Rol van de auteur​

De auteur staat in voor het aanbrengen van nieuwe artikelen. Dat gebeurt tussen het verschijnen van een editie van de blog en woensdagavond.

In detail houdt dit het volgende in:

  • Fork nemen van de repo: auteurs hebben niet de rechten om rechtstreeks te werken in de repository. Daarom moeten ze een fork maken van de originele repo en daarin werken. Wijzigingen aan de originele repo kunnen uiteraard wel voorgesteld worden adhv een merge request.
  • Een auteur zal elke week op zoek gaan naar een interessant artikel om toe te voegen aan de blog. Dat hoeft uiteraard niet volledig zelf geschreven te worden, je kan je baseren op wat bestaande blogs brengen. We mikken wel expliciet op nieuws dat relevant is voor wie professioneel bezig is met Infrastructure as Code.
  • Als een idee gevonden werd voor een artikel, dan wordt een issue aangemaakt. Op die manier is duidelijk wie waar aan het werken is. Zo wordt vermeden dat meerdere auteurs hetzelfde onderwerp aan het bespreken zijn.
  • Een auteur is inhoudelijk verantwoordelijk voor zijn artikel, en ook vormelijk moet het voldoen. Als dat niet zo is, zullen redacteurs het simpelweg weigeren.
  • Ten laaste op woensdag wordt een merge request gemaakt naar de bovenliggende repo waarvan geforked werd.
  • Merge request maken naar de bovenliggende, originele repo waarvan geforked werd.
Belangrijkste punten voor de blog-post zelf:
  • inhoudelijk relevant (i.v.m. Infrastructure as Code)
  • voorzien van minimaal één foto, schema,...
  • voorzien met correcte tag om de 'short' blog te bepalen.
  • Houd na het indienen van je Merge Request (MR) goed in de gaten of er feedback komt van je redacteurs. Er bestaat immers een kans dat je MR geweigerd wordt of enkele aanpassingen vergt.
    Normaal zal dit via feedback in je MR terug te vinden zijn. Als je notificaties actief zijn, zal je normaal ook een mailtje krijgen.

Rol van de redacteur​

De rol van de redacteur is de artikelen evalueren en samenvoegen met de reeds bestaande artikelen.

In detail:

  • Op donderdag gaat deze groep door de lijst van merge requests die de auteurs maakten en reviewen ze die. Het is de verantwoordelijkheid van de redacteurs dat de merge requests ook kunnen mergen (oa. pipeline checken). Is dat niet zo, dan zijn het de redacteurs die de merge request moeten updaten. (bv indien meerdere MR's binnengekomen zijn zullen er ongetwijfeld conflicten ontstaan waar de auteurs geen invloed op hebben)
  • Voor elke MR die opgenomen wordt, wordt dit ook via het issuebord in de juiste 'status' gebracht zodat andere redacteurs weten welke issues/MR's in behandeling zijn.
  • Auteurs krijgen feedback via hun MR (eventueel kan je bepaalde lijnen code van commentaar voorzien). Indien nodig moeten ze hun artikel nog aanpassen (inhoudelijk, tikfouten, ...)
  • Redacteur controleert image, samenvatting (tag), Markdown syntax,...
  • Als het artikel voldoet, zullen redacteurs het mergen met de develop-branch.
  • Als alles goed gaat zal het eindresultaat van de redacteurs bestaan uit een werkende nieuwe site op de develop-branch. Voor de buitenwereld is die nog niet zichtbaar.
  • Als het resultaat van alle toegevoegde en naar de development gemergde blog-posts gecontroleerd werd, kunnen de redacteurs een Merge Request naar de main aanmaken. Het is dan aan de projectleiders om die MR verder af te handelen.
  • Op het issue-bord verander je de status van issues die je behandeld hebt.

Rol van de projectleider​

De projectleiders houden het overzicht. Zij hebben als taak om op vrijdag de nieuwe site te lanceren.

  • De projectleiders zitten op donderdagnamiddag of uiterlijk vrijdag samen om te beslissen om al dan niet te mergen naar main.
  • 1 projectleider zet die merge klaar, maar minstens 1 andere projectleider moet ook toestemming geven vooraleer naar main gemerged wordt. Dat zal uiteraard enkel gebeuren als de testbuilds goeie resultaten geven.
  • De projectleiders zijn ook verantwoordelijk voor het dagelijks beheer van de site. Als vb een security patch moet toegepast worden, dan doen ze dat in develop, en wordt dat na goedkeuring van de andere projectleiders gemerged naar main.
  • De projectleiders hebben ook de belangrijke taak om via de Protected branches en de Merge request approvals in gitlab de redacteurs en projectleiders voor de volgende sprint vast te leggen!!

Git-vereisten​

We gebruiken de Gitlab-workflow. Een schematisch voorbeeldje zie je hier:

gitGraph commit commit branch develop checkout develop branch upgrade-component branch fork-auteur1-develop branch fork-auteur2-develop checkout fork-auteur1-develop commit id:"artikel" commit id:"artikel deel2" checkout develop merge fork-auteur1-develop checkout fork-auteur2-develop commit id:"artikeltje" commit id:"artikeltje deel2" checkout develop merge fork-auteur2-develop checkout upgrade-component commit id:"security fix" commit id:"upgrade component" checkout develop merge upgrade-component id:"merge nieuwe artikelen" checkout main merge develop id:"site-release" tag:"v 1.0.0"

Belangrijke punten hierbij:

  • op develop probeer je steeds een werkende versie te hebben. Je kan dit zien als de 'staging' omgeving
  • de main-branch is wat je site-bezoekers zien. Deze mag dus nooit voor experimenten gebruikt worden (zelfs kleine aanpassingen doe je niet rechtstreeks).

Gitlab-vereisten​

Naast een correct gebruik van Git, focussen we ook op een correct gebruik van Gitlab als platform.

Belangrijke punten hierbij:

  • Maak steeds gebruik van issues vooraleer je een branch maakt, en indien mogelijk link je je branches zoveel mogelijk met je issues.
  • Gebruik de verschillende borden in je project. Je moet op elk moment kunnen zien welke issues nog in de backlog zitten, welke momenteel behandeld worden en in welke fase ze zich bevinden.

Evaluatie​

Er wordt gequoteerd op:

  • Best practices gebruikt voor commit messages
  • Altijd gewerkt met feature branches
  • Kwaliteit van de wijzigingen
  • Halen van deadlines, en het volgen van de bovenstaande werkwijze
  • Aanmaken merge requests
  • Verwerken van de merge requests
  • Gebruik van team collaboration Gitlab-features zoals issues, borden, ...
  • ...