Blog

9 oktober 2018

Waar moet je op letten als je software open source maakt?

Wanneer je software open source maakt, is het natuurlijk de bedoeling dat anderen hier ook wat mee kunnen. Alleen het openbaar maken van de broncode is hiervoor niet genoeg. Het is minstens even belangrijk dat mensen snel overzicht kunnen krijgen over de software en over de structuur en de kwaliteit van de code. Ook moet duidelijk zijn hoe de code kan worden aangepast en welke juridische voorwaarden er gelden. Let daarom op de volgende zaken wanneer je software gaat open sourcen.

Check de code

Controleer of je het recht hebt om de gehele code openbaar te maken. Zorg dat interne opmerkingen en verwijzingen naar niet-openbare code worden verwijderd. Eventueel kun je gebruik maken van scantools zoals SonarQube en FOSSology, waarmee je code kunt controleren op kwaliteit en op gebruikte licenties. Zorg dat de code consistent is, zie ook hieronder bij Documentatie.

Documentatie

De documentatie moet niet alleen informatie voor ontwikkelaars bevatten, maar moet ook niet-technici een duidelijk beeld geven over het project. Dit kan door een gelaagd model te hanteren, waarbij elk onderwerp een eenvoudige introductie bevat en vervolgens stapsgewijs dieper op de technische aspecten wordt ingegaan. Documentatie verschaft niet alleen uitleg, maar zorgt ook er een eenduidige manier van werken is. Voor nieuwe bijdragers moet het eenvoudig zijn om aan te sluiten bij deze werkwijze. Een goed structuur van documentatie voorkomt dat ontwikkelaars het overzicht verliezen en bijvoorbeeld steeds opnieuw beslissingen nemen over hetzelfde punt. Consistentie is ook wenselijk met betrekking tot taalgebruik, schrijfstijl, opmaak en het gebruik van afbeeldingen. Veel bedrijven gebruiken hiervoor een eigen stijlgids, zie bijvoorbeeld de stijlgids van Google.

Gebruik van badges

Met badges geef je gebruikers eenvoudig inzicht in de kwaliteit van de code. Een badge toont bijvoorbeeld het aantal gemelde bugs, de dekking van de testen en een score voor de kwaliteit van de code.

Voorbeeld van badges op GitHub

Bron: https://github.com/ICTU/quality-report.

Door op een badge te klikken, krijg je toegang tot achtergrondinformatie zoals een kwaliteitsrapport of een dashboard met grafieken.

Versiesysteem

Hanteer een versiesysteem om de ontwikkeling van de software te expliciteren en communiceer dit naar de gebruikers. Een populair versiesysteem is Sematic Versioning (semver). In dit systeem wordt de basisversie van de software aangeduid als 1.0.0. Kleine aanpassingen zoals bug fixes worden bijgehouden in de derde kolom (1.0.1, 1.0.2, 1.0.3 etc.), nieuwe features die verder geen invloed hebben op de bestaande code in de tweede kolom (1.1.0, 1.2.0, 1.3.0 etc.) en grote aanpassingen van de code in de eerste kolom (2.0.0, 3.0.0, 4.0.0 etc.).

Maak de software configureerbaar

Anderen zullen de software voor hun eigen doeleinden willen gebruiken. Houd de code daarom vrij van branding zoals bedrijfsnamen, kleuren en logo’s. Door het toevoegen van configuratieopties zorg je ervoor dat gebruikers de branding zelf kunnen instellen.

Licenties

Voorzie de code van een open source licentie. Hiermee geef je anderen toestemming om de software aan te passen, te kopiëren en te verspreiden. Er zijn verschillende open source licenties, de onderlinge verschillen zien onder meer op het al dan niet toestaan van commercieel gebruik en de verplichting om afgeleide werken onder dezelfde licentie te publiceren. Het is raadzaam om te kiezen voor een licentie die algemeen bekend is en vaak wordt gebruikt. Voorbeelden van dergelijke licenties zijn EUPL, AGPL en GPL. Voor een overzicht van verschillende open source licenties, zie de website van het Open Source Initiative.

De bovenstaande licenties zijn alleen van toepassing op software. Voor de teksten van de documentatie wordt vaak een Creative Commons-licentie gekozen, bijvoorbeeld CC BY-SA 4.0.

Omgang met bijdragen

Omschrijf hoe je omgaat met aanpassingen (pull requests) vanuit de community en leg dit vast in een contributors guide. Hierin staat hoe ontwikkelaars aan het project kunnen meehelpen en aan welke voorwaarden hun bijdragen moeten voldoen. Zo moet meestal Engels worden gebruikt en zijn er vaak specifieke instructies voor rapporteren van beveiligingsproblemen. Ook bevat het document vaak een gedragscode (code of conduct) en informatie over reactietermijn voor ingediende bijdragen, de gang van zaken rondom afgewezen bijdragen en het vragen om hulp. Soms wordt verwezen naar een stappenplan voor nieuwe leden van de community en naar een stijlgids. De contributors guide van GitLab bevat al deze elementen, plus juridische voorwaarden en licentievoorwaarden die op alle bijdragen van toepassing zijn.

Auteursrecht op bijdragen

In principe verkrijgt iedereen die bijdraagt aan het project auteursrecht op elke eigen bijdrage. Zorg er dus voor dat ontwikkelaars ermee instemmen dat voor hun bijdragen dezelfde licenties gelden als voor de rest van het project. Dit kan door een Contributor License Agreement (CLA) of een Developer Certificate of Origin (DCO) af te sluiten. Een CLA bevat de precieze voorwaarden waaronder het intellectueel eigendom op bijdragen geheel of gedeeltelijk wordt overgedragen. Met een DCO verklaart de ontwikkelaar dat elke bijdrage zelf gemaakt dan wel naar diens beste weten vrij is van rechten van derden. GitLab gebruikt een gecombineerd document, Developer Certificate of Origin + License. GitHub heeft een tool ontwikkeld die bij elke commit automatisch om een DCO vraagt.

Automatisch testen

Maak gebruik van automatische testen (CI/CD) om elke bijdrage automatisch te controleren. Zorg ook voor integraties met GitHub of GitLab, zodat het testresultaat direct wordt weergegeven bij het indienen van een pull request.

Checklist

Overal aan gedacht? De Linux Foundation heeft een checklist uitgebracht voor het lanceren van open source projecten. Deze kan ook behulpzaam zijn bij het open source maken van bestaande projecten. De checklist vind je onderaan deze pagina.