Aan de slag met development
Last updated
Last updated
We gaan er voor deze stap vanuit dat je reeds een werkende lokale Nextcloud-omgeving hebt met daarin de code voor de app, heb je die nog niet kijk dan eerst onder Installatie van of-omgeving
Als Nextcloud-app volgen we sowieso de .
Daarbovenop hanteren we een aantal extra spelregels:
Features moeten zijn voorzien van gebruikersdocumentatie
Backend code moet zijn voorzien van automatische tests: Code die coverage van het project verlaagd wordt niet geaccepteerd, zie ook .
Backend code moet zuiver zijn: Code mag géén linting errors bevatten
Frontend code moet zijn voorzien van automatische tests: Code die coverage van het project verlaagd wordt niet geaccepteerd
Frontend code moet zuiver zijn: Code mag géén linting errors bevatten
Seperation of concerns: Voor zowel backend als frontend moet business logica zijn opgenomen in Services. Dat betekent dat Controllers, Templates, Views, Componenten en Store géén business logica mogen bevatten.
Vier ogen-principe: Pull requests moeten zijn beoordeeld door een andere developer dan de maker voordat ze worden geaccepteerd
Automatische test: Code mag alleen naar master/main als alle automatische tests goed gaan
Vraag gestuurde development: Code wordt alleen geaccepteerd als deze is gekoppeld aan een door de PO goedgekeurde user story ()
In de meeste gevallen zal een wijzigingsvoorstel voor de OpenCatalogi Nextcloud app voortkomen vanuit de PO owner van OpenCatalogi () of de product owner van een van de . Maar feitelijk kan iedere gebruiker een feature request indienen.
Als onderdeel van de CI/CD-straat voeren we een aantal tests uit, hiermee handhaven we zowel de code kwaliteiteisen van Nextcloud als die van onszelf. Deze testen worden geborgd in een workflow zodat je de resultaten zelf op iedere commit ziet. Let op! het falen van deze tests betekent dat de code niet naar master/main kan worden gemerged en dus niet in productie kan worden genomen.
Voorzowel de frontend als de backend geldt dat het aantal acceptabele errors 0 is.
Voor beide geldt dat minimale test coverage 80% is, en het aantal acceptabele errors 0.
XDEBUG_MODE=coverage phpunit --bootstrap ./tests/bootstrap.php --configuration phpunit.xml --coverage-html ./coverage --coverage-text | tee coverage.txt
NOTE 2 Unit testing doe je in een draaiende container van Docker. Hiervoor kijk je met
docker psnaar de draaiende containers. De container heetnextcloudofmaster_nextcloud_1. Het commando om in de container te komen is:docker exec -it [containernaam] /bin/bash. Je komt dan met root priviliges invar/www/htmlen moet nog navigeren naar de juiste directory met het commandocd apps-exta/opencatalogi. Daar werken dephpunit-commando's voor het uitvoeren van de unit tests.
Voor beide geldt dat het aantal acceptabele critical vulnerabilities 0 is.
We gebruiken Gitbook voor de gebruikersdocumentatie. Features binnen de app zouden zo veel mogelijk direct moeten doorverwijzen naar deze documentatie.
Daarnaast gebruiken we Typescript voor het definiëren van entities.
Er mag altijd slechts één modal actief zijn.
Modals moeten abstract en overal bereikbaar zijn.
Modals moeten geplaatst worden in de map src/modals.
Modals moeten getriggerd worden via de state (zodat knoppen die modal openen overal plaatsbaar zijn).
Modals moeten geïmporteerd worden via /src/modals/Modals.vue.
Views moeten dezelfde bestandsnaam hebben als de geëxporteerde naam en een correlatie hebben met de map waarin het bestand zich bevindt.
Bijvoorbeeld, als het bestand een detailpagina is en het zich in de map publications bevindt, moet het bestand de naam PublicationDetail.vue hebben.
Het is goed om bij development kennnis te nemen/hebben van de volgende gebruikte Nextcloud onderdelen:
De Ontwikkelpartijen van fungeren tevens als beheerpartijen voor de code base.
Omdat de applicatie is ontwikkeld met Nextcloud, is er uitgebreide informatie te vinden in de zelf. Dit geldt zowel voor de lay-out van de app als voor de vele componenten die eraan toegevoegd kunnen worden. Tijdens de ontwikkeling van de OpenCatalogi-app is het documentation-first principe gehanteerd, waarbij de ontwikkelaars eerst de hebben geraadpleegd.
Voor frontend gebruiken we ESLint, de installatiehandleiding is te vinden. Het commando om ESLint uit te voeren. ESLint is voornamelijk een linter, met enige format-functionaliteit.
Voor de backend gebruiken we PHP Code Sniffer. de handleiding voor de installatiemogelijkheden. PHP-code sniffer bestaat uit een linter ( phpcs) en een formatter(phpcbf). De formatter werkt hetzelfde als de linter en kan soms aardig wat errors wegwerken. De regels voor zowel de linter als de formatter zijn te vinden in phpcs.xml in de root van de applicatie.
Voor het uitvoeren van de unit tests gebruiken we aan de frontend Jest. Indien je deze nog moet installeren of meer erover wilt weten, kijk dat . Het uit te voeren commando is:
Voor het uitvoeren van de unit tests gebruiken we aan de backend PHPunit. Indien je deze nog moet installeren of meer erover wilt weten, kijk dan . Het uit te voeren commando is:
NOTE 1 We volgen de Nextcloud wijze voor unit testing, zie hier voor , maar dit komt neer op en de juist configuratie van phpunit.xmlen de bootstrap.php. Een voorbeeld van deze files zijn te vinden in de root van de applicatie (phpunit.xml) en de /tests/unit(bootstrap.php). Er zijn veel mogelijkheden om het jezelf makkelijk te maken, zoals een percentageoverzicht in de terminal. Het commando dat wij gebruiken is :
Ook voor de documentatie wordt een linter gebruikt namelijk .
De commando's om deze linter in de CLI te gebruiken zijn voor een uitgebreide output in de terminal.
De ontwikkeling van de API wordt bijgehouden met de documentatietool , die automatisch een genereert uit de documentatie. De Stoplight voor OpenCatalogi is te vinden.
Om gegevens deelbaar te maken tussen de verschillende Vue-componenten maken we gebruik van waarbij we het Action, State, View patroon van Vue zelf volgen. Omdat de applicatie ingewikkeld begint te worden stappen we daarbij over van naar , de door Vue zelf geadviseerde opvolger van .
-
