GitHub biedt functionaliteit om documenten te publiceren vanuit een repository. Logius gebruikt deze functionaliteit om het met ReSpec gegenereerde document te publiceren als HTML-document en een PDF-document. Deze documenten worden automatisch gekopieerd naar een publicatiewebsite onder Logiusbeheer.
Het proces zoals beschreven onder operationeel beheer, wensen en eisen wordt voor de Logius standaarden geïmplementeerd door gebruik te maken van GitHub issues. Een issue kan binnen GitHub ingediend worden door iedere (GitHub)gebruiker en wordt bij ontwikkeling van code gebruikt om functionele wensen of gevonden bugs in te dienen zodat deze door ontwikkelaars opgepakt kunnen worden. Een issue kan online besproken worden en uiteindelijk gesloten worden wanneer deze verwerkt is. Alle open en gesloten issue's blijven publiek inzichtelijk in de repository van de door Logius beheerde standaard.
Binnen het standaardenbeheer bij Logius maken we gebruik van verschillende branches. De main branch bevat de laatste formeel geaccepteerde versie van een document. De develop branch bevat een werkversie met daarin alle wijzigingen die in een volgende geaccepteerde versie opgenomen moeten worden.
Aanpassingen in de documentatie die voor een specifiek wijzigingsvoorstel gemaakt worden worden in eigen branch verwerkt. Deze branch wordt gesplitst vanaf de develop branch en wordt nadat het wijzigingsverzoek aangenomen is teruggebracht naar de develop branch.
Voorbeeld: een wijzigingsverzoek voor het aanpassen van de architectuurbeschrijving zal in een branche nieuwe architectuur worden verwerkt. Deze wordt gesplitst vanaf, en teruggebracht naar, de develop branch. Door wijzigingen in een eigen branch op te nemen zijn alle wijzigingen op de documentatie inzichtelijk per wijzigingsvoorstel.
De develop branch wordt dus niet gebruikt om wijzigingen op het document te maken maar dient als verzamelbranch voor de verschillende wijzigingen die in een volgende release moeten komen. Patches kunnen wel direct op de develop branch worden doorgevoerd.
Deze sectie geldt niet voor commits die worden gemaakt tijdens het werk aan een pull request.
Commit messages zijn voor maintainers en derden belangrijk om een (historisch) beeld te krijgen van de evolutie van een standaard. Om het onderscheid duidelijk te maken tussen normatieve en niet-normatieve wijzigingen, moeten commits met enkel niet-normatieve wijzigingen starten met Beheer:. Probeer ook zoveel mogelijk wijzigingen te groeperen in commits die enkel normatieve wijzigingen toepassen en commits die enkel niet-normatieve wijzigingen bevatten. Als deze worden gegroepeerd in (grote) commits, dan wordt het voor de lezer (en voornamelijk implementeerders) lastiger om te weten wat er in code moet worden veranderd om aan de standaard te voldoen.
Voorbeeld van een commit met enkel niet-normatieve wijzigingen:
Beheer: update copyright jaar
Voorbeeld van een commit met enkel normatieve wijzigingen:
Vereis dat alle URLs eindigen zonder een slash
Normatieve wijzigingen moeten geen prefix hebben en duidelijk uitleggen waar de wijziging over gaat, met in acht nemen van de generiek (Engelse) guide voor het schrijven van bruikbare commit messages. In tegenstelling tot de gelinkte guide moeten commit messages in het Nederlands worden geschreven.
Om dit te vergemakkelijken wordt "Squash and merge" aangeraden. Dit stelt in staat om bij het mergen de commit message in de correct structuur te krijgen, zodat de commits tijdens de pull request flexibeler kunnen zijn.
In de commit message body wordt aangeraden om de volgende informatie toe te voegen:
- Achtergrond informatie wat de meerwaarde van de wijziging is
- Eventuele tips/tricks voor implementeerders hoe een wijziging kan worden geintegreerd in bestaande implementaties
- Link naar het TO waarin de wijziging is geaccepteerd
- GitHub notatie van issues die hiermee opgelost zijn
Om GitHub issues te classificeren en te agenderen voor het juiste overleg maken we gebruik van een aantal standaard labels. We labelen binnenkomende issues als:
- Type Alle soorten issues kunnen binnenkomen. Met Type sorteren we de issues in vragen, correcties en wijzigingen.
- Correctie
- Documentatie
- Vraag
- Wijziging
- Scope Vooral relevant voor wijzigingsvoorstellen. Hiermee wordt aangegeven of het een kleine of grote wijziging betreft. Dit heeft betrekking op de impact van een wijziging en daarmee op de versienummering.
- Klein
- Groot
- Overleg Het label Overleg heeft alleen betrekking op wijzigingsvoorstellen. Wanneer deze labels gebruikt worden wordt het voorstel geagendeerd voor het betreffende overleg.
- TO-DK
- TO-Auth
- Gegevensuitwisseling
- Toegang
- Interactie
- Infrastructuur
- Status
- In onderzoek
- In bewerking
- Uitwerking door derden
- In review
- Klaar voor review
- Gereed
- Afgewezen
GitHub ondersteunt automatisering van taken door scripts. Standaard is de publicatie via github pages. Binnen de Logius standaarden maken we gebruik van scripts om documenten te publiceren, links te checken en om een paar eenvoudige tests op digitoegankelijkheidseisen uit te voeren.