💻 computer science

The Impact of Documentation on Test Engagement in Pull Requests in OSS

Dit onderzoek toont aan dat een betere documentatie over testen een positieve correlatie heeft met de bereidheid van open-source bijdragers om tests toe te voegen aan hun pull requests.

Oorspronkelijke auteurs: Teal Amore, Nathan Berman, Siyuan Jiang

Gepubliceerd 2026-04-28

📖 3 min leestijd☕ Koffiepauze-leesvoer

CC BY 4.0

Oorspronkelijke auteurs: Teal Amore, Nathan Berman, Siyuan Jiang

Oorspronkelijk artikel gelicentieerd onder CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Dit is een AI-gegenereerde uitleg van het onderstaande artikel. Het is niet geschreven of goedgekeurd door de auteurs. Raadpleeg het oorspronkelijke artikel voor technische nauwkeurigheid. Lees de volledige disclaimer

Stel je voor dat je meedoet aan een enorme, wereldwijde kookwedstrijd (dat is de Open Source Software-wereld). Iedereen mag recepten (code) insturen om de grote digitale keuken te verbeteren. Maar er is één probleem: veel mensen sturen alleen het recept voor de taart, maar vergeten de instructies voor de 'testkeuken' mee te sturen. In die testkeuken moet je controleren of de taart niet te zout is of niet in elkaar stort.

Zonder die tests kan de hele digitale keuken een puinhoop worden.

Het probleem: De vergeten controleur

In de softwarewereld is het heel moeilijk om mensen te motiveren om ook die extra testjes te schrijven. Meestal pas je pas in als het misgaat: de chef-kok (de reviewer) ziet dat de taart niet getest is en zegt: "Hé, je bent de test vergeten!" Dat is reactief: het probleem is er al, en je probeert het achteraf te repareren.

De onderzoekers van deze studie vroegen zich af: kunnen we het slimmer aanpakken? Kunnen we mensen vooraf helpen door een soort 'kookboek met instructies' (documentatie) aan te bieden?

De nieuwe meetlat: De "Test-Gierigheid-Index" (TER)

De onderzoekers bedachten een nieuwe manier om te meten hoe enthousiast mensen zijn om te testen. Ze noemen dit de Test Engagement Ratio (TER).

Zie het zo: als je 10 nieuwe gerechten indient, en bij 4 daarvan stuur je ook een lijstje met proefsmakers mee om de smaak te controleren, dan is je "test-gierigheid" 40%. Het is een simpele manier om te zien of mensen de testkeuken serieus nemen, zonder dat we de hele keuken hoeven te verbouwen om het te meten.

Wat hebben ze ontdekt? (De resultaten)

Ze hebben naar 160 grote digitale keukens gekeken en vonden iets heel interessants:

De handleiding werkt: Projecten die een uitgebreid "kookboek" hebben met veel verschillende instructies over testen, hebben veel meer mensen die ook echt testen. Het is alsof je een nieuwe kok een duidelijke handleiding geeft: de kans is veel groter dat hij de regels volgt.
De belangrijkste hoofdstukken: Het werkte niet voor alle instructies even goed. De hoofdstukken "Hoe voer ik de tests uit?" en "Hoe schrijf ik een test?" waren de absolute winnaars. Dat is logisch: als je niet weet hoe je de oven moet aanzetten, ga je ook niet testen!
Populariteit helpt niet: Het maakte niet uit of een project een "sterrenrestaurant" was (veel volgers op GitHub) of een kleine lokale bistro. De aanwezigheid van goede instructies was belangrijker dan hoe beroemd het project was.

De conclusie in gewone mensentaal

De onderzoekers hebben bewezen dat je mensen niet alleen moet corrigeren nadat ze een fout hebben gemaakt, maar dat je ze het beste kunt helpen door ze van tevoren een goede routekaart te geven.

Als je in een softwareproject duidelijk opschrijft hoe je de tests moet gebruiken, gaan ontwikkelaars vanzelf vaker testen. Het is de digitale versie van: "Niet alleen vertellen dat de taart lekker moet zijn, maar ook even laten zien waar de suiker staat en hoe de thermometer werkt."

Technische Samenvatting: De impact van documentatie op testbetrokkenheid in Pull Requests in OSS

Probleemstelling

In Open Source Software (OSS) is het essentieel dat bij code-wijzigingen ook tests worden toegevoegd om de softwarekwaliteit te waarborgen. De huidige methoden om dit te stimuleren (zoals code coverage-metrieken of feedback van reviewers) zijn echter vaak reactief: ze treden pas in werking nadat een pull request (PR) al is geopend. Dit biedt weinig educatieve waarde voor de ontwikkelaar tijdens het schrijfproces. Het onderzoek onderzoekt of documentatie over testen kan dienen als een proactieve maatregel om ontwikkelaars aan te moedigen vaker tests te schrijven.

Methodologie

De onderzoekers analyseerden data van 160 OSS-repositories. De methodologie rust op drie pijlers:

Nieuwe Metriek: Test Engagement Ratio (TER): Omdat het berekenen van traditionele metrieken zoals code coverage op grote schaal technisch complex is (vanwege build-problemen), introduceerden de auteurs de TER. Deze metriek meet de verhouding tussen PR's die zowel productiedocumentatie als testbestanden wijzigen, versus PR's die alleen productiedocumentatie wijzigen. Dit dient als een schaalbare proxy voor testgedrag.
Documentatie-diversiteitsscore: De uitgebreidheid van de documentatie werd gekwantificeerd door het aantal aanwezige testcategorieën (bijv. "Hoe tests uit te voeren", "Unit testing", etc.) te tellen. Er werden 10 categorieën gedefinieerd.
Data-analyse: Er werd gebruikgemaakt van Spearman’s rangcorrelatiecoëfficiënt ( $\rho$ ) om de relatie tussen de documentatiescore en de TER te bepalen, aangezien de data niet normaal verdeeld was. Daarnaast werd de validiteit van de TER getoetst door deze te vergelijken met de bestaande Test Code Ratio.

Belangrijkste Bijdragen

Introductie van de TER-metriek: Een nieuwe, computationeel efficiënte manier om de frequentie van testen in OSS-projecten te meten zonder de noodzaak om de volledige testsuite van elk project uit te voeren.
Empirisch bewijs voor proactieve documentatie: Het eerste onderzoek dat een statistisch verband aantoont tussen de aanwezigheid van testinstructies in de documentatie en het daadwerkelijke testgedrag van bijdragers.
Identificatie van kritieke documentatiecategorieën: Het onderzoek wijst specifiek aan welke soorten instructies de grootste impact hebben op het gedrag van ontwikkelaars.

Resultaten

RQ1 (Correlatie met uitgebreidheid): Er is een zwakke maar statistisch significante positieve correlatie ( $\rho = 0,36, p < 0,001$ ) tussen de uitgebreidheid van de documentatie en de TER. In actieve repositories met veel PR's versterkt dit verband zich tot een matige correlatie ( $\rho = 0,44$ ).
RQ2 (Specifieke categorieën): De categorieën "How to Run Tests" ( $\rho = 0,34$ ) en "How to Write Tests" ( $\rho = 0,36$ ) vertonen de sterkste correlatie met testbetrokkenheid. Populariteitsmetrieken van het repository (zoals sterren of forks) bleken geen invloed te hebben op de testbetrokkenheid.
RQ3 (Validatie): De TER vertoont een matige positieve correlatie ( $\rho = 0,52$ ) met de standaard Test Code Ratio, wat de validiteit van de nieuwe metriek ondersteunt.

Significantie en Toekomstig Werk

Dit onderzoek is significant omdat het aantoont dat het verbeteren van de contribution guidelines een effectieve, proactieve strategie kan zijn om de softwarekwaliteit in OSS te verhogen. In plaats van ontwikkelaars achteraf te corrigeren, kunnen maintainers door middel van heldere instructies de testcultuur vanaf het begin stimuleren.

Toekomstig onderzoek zal zich richten op:

Het vaststellen van causaliteit (via een difference-in-differences ontwerp).
Het analyseren van de kwaliteit van de documentatie op een granulair niveau.
Het onderzoeken van het exposure-effect: of ontwikkelaars die in het ene project leren testen door goede documentatie, dit gedrag meenemen naar andere projecten.