Aanpassen van het Algoritmekader

Op deze pagina vind je een instructie die je kan volgen als je aanpassingen wilt maken aan het Algoritmekader.

Warning

Deze instructie gaat ervanuit dat je schrijfrechten hebt op het Algoritmekader. Vraag deze rechten aan, indien je deze nodig denkt te hebben of maak gebruik van een fork.

Voordat je gaat beginnen met aanpassen

Voordat je gaat beginnen zijn er een paar dingen die handig zijn om te weten:

• We werken met het vier-ogen-principe. Dat betekent dat je nooit zomaar een aanpassing kan doen, maar er altijd een review van een collega nodig is. Een collega moet jouw wijziging altijd goedkeuren.
• Wijzigingen zijn niet gelijk zichtbaar op de website. Deze worden pas zichtbaar nadat er een nieuwe release is aangemaakt.
• Github terminologie. Github maakt gebruik van een aantal termen, waarvan het handig is om te weten wat ze betekenen.

term	uitleg
issue	een taak die uitgevoerd kan worden. Dit kan bijvoorbeeld een vraag zijn of het project of een suggestie voor het project
commit	snapshot van het project op een bepaald moment
branch	nieuwe / aparte versie van het project, een kopie waarin je wijzigingen kan aanbrengen
pull-request	voorstel voor wijzigingen
merge	samenvoegen van verschillende wijzigingen uit verschillende branches
release	nieuwe versie van het project, met een versienummer

Hoe deze begrippen met elkaar samenhangen blijkt uit onderstaand figuur:

Stappenplan aanpassing doen in Github

Stap 1: maak een Github account

Maak een Github account aan, of log in op Github.

Stap 2: Ga naar de repository

Ga naar de repository van het Algoritmekader.

Stap 3: Aanmaken nieuwe branch

Maak een nieuwe branch aan. Dit is een kopie van het Algoritmekader, waarin je jouw aanpassingen kan doen. Geef de branch een logische naam. In dit voorbeeld is dat release-v2.2/add-dots. De main branch is de hoofdversie van het Algoritmekader. In principe is dit de versie die online staat. Indien je al een branch hebt aangemaakt, dan navigeer je op dezelfde wijze naar jouw branch.

Stap 4: Navigeer naar het bestand dat je wilt aanpassen

Navigeer vervolgens naar het bestand dat je wilt aanpassen. Als je het bestand niet kan vinden, lees dan eerst meer over de bestandsindeling.

Note

Wil je een nieuw bestand aanmaken i.p.v. een bestaand bestand aanpassen? Navigeer dan naar de juiste map en klik bovenin op Add file en vervolgens op Create new file. Kies nu de juiste bestandsnaam zodat dit past in de structuur. Let hier op de volgende aspecten:

• bij maatregelen en vereisten bepaalt de bestandsnaam de volgorde van de maatregelen en de vereisten. Houd hier dus rekening mee.
• bestandsnamen mogen geen spaties bevatten. Gebruik daarom - als koppelteken.
• de extensie van het bestand moet zijn .md. Dat geeft aan het het een markdown bestand is (een type bestand voor platte tekstbestanden).

Stap 5: Pas het bestand aan

Klik rechtsboven op het potloodicoontje: Je komt nu in de edit-mode van het betreffende bestand. Hier kan je een wijziging doen in de tekst.

Stap 6: 'Commit' je aanpassingen

Als je klaar bent met je wijziging klik je op commit changes rechtsbovenin.

• Geef bij de commit message een duidelijke omschrijving mee van je aanpassing.
• Indien je meer wijzigingen in 1x wilt doen, kan je dit op dezelfde manier doen in dezelfde branch.

Stap 7: Open een pull-request

Als je klaar bent met je wijzigingen is het tijd voor een review van een collega. Dit doe je door een pull-request aan te maken. Een pull-request is een voorstel om een set van wijzigingen uit een branch samen te voegen met een andere branch. In ons geval wil je altijd jouw wijzigingen uit je eigen branch (in het voorbeeld release-v2.2/fix-typo) samenvoegen met de main branch. Dan worden jouw wijzigingen ook doorgevoerd in de main branch.

• Klik op Code linksboven om terug te gaan naar alle bestanden in jouw branch.
• Bovenin verschijnt nu een tekstblok waarin staat aangeveven wanneer de laatste wijzigingen in jouw branch zijn gemaakt. Klik hier op de knop Compare & pull-request om een pull-request aan te maken.
• Geef jouw voorstel een titel en geef een duidelijke beschrijving van de aanpassingen die je hebt gedaan.
• Klik op Create pull-request of Create draft pull request. Draft pull request betekent dat het nog in concept is. Dit geeft dus aan dat je nog bezig bent met jouw wijzigingen.

Stap 8: Bekijk de wijzigingen die je hebt gedaan.

Nadat je een pull-request hebt aangemaakt, kan je zelf nog controleren of de wijzigingen die je hebt gedaan kloppen. Dit kan op twee manieren:

• Tijdelijke preview: Nadat je een pull-request hebt aangemaakt, wordt er automatisch een tijdelijke preview van de website met jouw wijzigingen erin aangemaakt. Dit is een tijdelijke link, die het mogelijk maakt dat je kan zien hoe jouw wijzigingen er straks uit zien op de website. Je kan deze link vinden in de pagina van de pull-request door onderstaand 'bericht' (herkenbaar door de raket 🚀). Bij elke aanpassing (of 'commit') die je doorvoert, wordt deze preview ververst. Let op: soms duurt het 1 of 2 minuten voordat de preview-link is gegenereerd of ververst.

• Alleen de wijzigingen bekijken: Een andere optie is om alleen de wijzigingen die je hebt gedaan te bekijken. Klik hiervoor op de tab Files changed. Hierin zie je alle bestanden die gewijzigd zijn in deze branch.

Stap 9: Aanvullen informatie in pull-request

Als je zelf tevreden bent met je wijzigingen, vul je de informatie in de pull-request nog verder aan. Vul het volgende in:

• Geef aan bij welk issue jouw wijzigingen horen. Lees meer in de wiki over hoe we gebruik maken van issues in het Algoritmekader. Je kan hier het nummer invullen (als je die weet) of je kan zoeken. Door het koppelen van een issue aan een pull-request wordt de issue automatisch gesloten wanneer de pull-request wordt afgerond.

• Doorloop de checklist en vul de vinkjes in.

• Indien je pull-request nog op draft staat, zet je deze nog op Ready for review.

Stap 10: Vraag een collega om te reviewen

Vraag nu een collega om jouw pull-request te reviewen. Eventueel kan je die collega 'assignen' aan het betreffende pull-request

Het reviewen van een pull-request

Een collega heeft gevraagd of je een pull-request wil reviewen. Wat nu?

Stap 1: Open de pull-request

Open de betreffende pull-request.

Stap 2: Bekijk de wijzigingen

Bekijk de wijzigingen die je collega heeft gemaakt. Er zijn twee manieren om de wijzigingen te bekijken:

• Tijdelijke preview: Nadat je een pull-request hebt aangemaakt, wordt er automatisch een tijdelijke preview van de website met jouw wijzigingen erin aangemaakt. Dit is een tijdelijke link, die het mogelijk maakt dat je kan zien hoe jouw wijzigingen er straks uit zien op de website. Je kan deze link vinden in de pagina van de pull-request door onderstaand 'bericht' (herkenbaar door de raket 🚀). Bij elke aanpassing (of 'commit') die je doorvoert, wordt deze preview ververst. Let op: soms duurt het 1 of 2 minuten voordat de preview-link is gegenereerd of ververst.

• Alleen de wijzigingen bekijken: Een andere optie is om alleen de wijzigingen die je hebt gedaan te bekijken. Klik hiervoor op de tab Files changed. Hierin zie je alle bestanden die gewijzigd zijn in deze branch.

Stap 3: Plaats opmerkingen bij het voorstel voor wijzigingen

Als je opmerkingen of suggesties hebt op de tekst, kan je dit doorgeven via de pull-request.

Stap 4: Beoordeel de wijzigingen

Er zijn nu een paar opties:

• comment: algemene feedback, zonder dat je er een oordeel over geeft.
• approve changes: hiermee geef je aan dat je akkoord bent met de voorgestelde wijzigingen.

• suggest changes: hiermee geef je aan dat je vindt dat er nog wijzigingen plaats moeten vinden voordat je dit goedkeurt.

Vervolgens moet degene die de pull-request heeft aangemaakt kijken naar jouw suggesties. Je kan suggesties gelijk 'comitten'. Uiteindelijk moet er een approve zijn van een andere collega voordat de wijzgingen kunnen worden doorgevoerd.

Stap 5: Merge de pull-request

Na een approve van een collega kan de wijziging worden gemergd met de main branch.

Verwijder na het mergen de desbetreffende branch.