CONTRIBUTING.md
Een goede CONTRIBUTING.md helpt potentiële bijdragers om efficiënt en effectief bij te dragen aan een project.
Wat neem je erin op?
1. Introductie
Een korte uitleg over het project en waarom bijdragen belangrijk zijn. Eventueel een verwijzing naar de doelstellingen of missie van het project.
2. Hoe je kunt bijdragen
- Bijdragen aan de code (bugfixes, nieuwe features, refactoring).
- Aandragen van issues (feature requests).
- Deelnemen aan discussies (op Mattermost, Github, Slack of een ander platform).
- Documentatie verbeteringen.
- Testen en bug reports indienen.
- Design, UX of accessibility verbeteringen.
3. Voordat je begint
Waar moet je rekening mee houden als je een bijdrage wilt doen? Verwijs naar de lijst met bestaande issues en leg uit hoe je een nieuwe issue opent. Geef aan of je eerst met de maintainers dient te overleggen voordat je een grote feature aandraagt.
4. Technische richtlijnen
- Code style: verwijzing naar linters, formattering, en naming conventions.
- Commit messages: bijvoorbeeld conventies zoals Conventional Commits.
- Pull requests: hoe je een PR indient.
- Reviewproces: hoe de feedbackloop werkt en wie reviews uitvoert.
5. Opzetten van de ontwikkelomgeving
- Hoe je het project lokaal installeert en draait.
- Vereisten zoals dependencies, SDK's, en buildtools.
- Eventuele scripts om het project snel op te zetten.
- Heb je documentatie voor het lokaal opzetten van het project in de
README.md? Link hier dan vooral naartoe.
6. Tests en kwaliteitscontrole
- Hoe je tests draait en toevoegt.
- Code coverage en teststrategie (unit, integration, e2e).
- Continuous Integration: welke checks en pipelines draaien er?
- Zorg ervoor dat bijdragers zelf alle tests lokaal kunnen vinden en draaien.
7. Gedragscode
- Verwijzing naar een
CODE_OF_CONDUCT.md(indien van toepassing). - Noem de basisprincipes voor een inclusieve en respectvolle samenwerking.
- Geef aan met wie een deelnemer contact kan opnemen in het geval dat de gedragscode wordt geschonden.
8. Licentie en juridische zaken
- Vertel onder welke licentie bijdragen vallen.
- Welke implicaties heeft de licentie voor de developer?
- Of bijdragers een Contributor License Agreement (CLA) moeten tekenen.
9. Bestuur
Wie bepaalt welke bijdragen uiteindelijk wel en niet worden geaccepteerd? Verwijs eventueel naar de GOVERNANCE.md. Vermeld onder dit kopje ook wie er betaalt voor het beoordelen en verwerken van de bijdragen. Als meerdere organisaties bij het project betrokken zijn, neem ze dan op in een lijst en benoem hun rollen.
10. Contact en ondersteuning
- Hoe en waar je vragen stelt (bijv. Discord, Slack, GitHub Discussions).
- Wie je kunt benaderen voor hulp.
- Vermeld hier ook contactgegevens (bijv. e-mailadressen)
- Voeg hier ook links toe naar communicatiekanalen (Slack, Mattermost, Mastodon).
Voorbeelden
- Zie de contributing guidelines van OpenKAT.
Voorbeeld: de CONTRIBUTING.md OSPO-NL:
./CONTRIBUTING.md
# Contributing Guide
> _Voor het maken van een eigen CONTRIBUTING kijk onderaan bij [Attribution](#attribution)_
Om te beginnen, hartelijk dank voor je interesse om bij te dragen aan dit OSPO-NL initiatief! Door
te delen in kennis en ervaring en samen te werken komen we tot 'best practices' en hulp om Open
Source projecten in Nederland goed te organiseren.
> **For non-Dutch native readers**: First off, thank you for your interest to contribute to this
> OSPO-NL initiative! By sharing knowledge and experiences and collaborate we'll be able to produce
> Best Practices and help to set up Open Source projects in The Netherlands. Because the gap between
> needs and knowledge in The Netherlands the content of this initiative will be mainly in Dutch.
>
> We are very sorry if this creates a feeling of not being inclusive ... which is of course against
> our [Code of Conduct](CODE_OF_CONDUCT.md); We would like to be as inclusive as possible!
>
> BUT to choose to write mainly in Dutch we will be more inclusive to the less equiped and Dutch
> native readers of our content and those are the primary focus of these practices. Nonetheless,
> much content is probably not managed here or produced inside these repositories but will be linked
> to or just translated summaries of content elsewhere.
Door deze richtlijnen te volgen, communiceer je dat je de tijd respecteert van de ontwikkelaars die
dit open source-project beheren en ontwikkelen. In ruil daarvoor moeten ze dat respect beantwoorden
bij het aanpakken van uw melding, het beoordelen van wijzigingen en het helpen afronden van uw pull
requests.
Houd een open geest! Het verbeteren van documentatie, melden van fouten, of bijdragen aandragen zijn
voorbeelden van nuttige bijdragen. Veel informatie is mogelijk al ergens beschikbaar, waarschijnlijk
in het Engels, en het verwijzen naar andere documentatie helpt ons allemaal. Helemaal als daar
samenvattingen (of volledige) vertalingen van in het Nederlands toegevoegd worden (daar of in dit
project)!
Mochten bijdragen niet voldoen aan deze richtlijnen dan houden wij ons de vrijheid om commentaren te
negeren en bijdragen te sluiten. Daarbij zullen wij verwijzen naar deze richtlijnen / Contributing
Guide.
> En als je het project leuk vindt, maar gewoon geen tijd hebt om bij te dragen, is dat prima. Er
> zijn andere eenvoudige manieren om het project te steunen en je waardering te tonen, waar we ook
> erg blij mee zijn:
>
> - Geef het project een ster
> - Tweet erover
> - Verwijs naar dit project in de readme van uw project
> - Noem het project op lokale meetups en vertel het aan je vrienden/collega's
## Basisregels
### Gedragscode
Dit project en iedereen die eraan deelneemt, wordt bestuurd door de [OSPO-NL
Gedragscode](CODE_OF_CONDUCT.md). Door deel te nemen, wordt van u verwacht dat u zich aan deze code
houdt. Gelieve onaanvaardbaar gedrag te melden volgens de
[Gedragscode#Handhaving](CODE_OF_CONDUCT.md#handhaving).
### Verwachtingen
Vrijwel alle content is beschreven in Markdown. Daarbij maken wij gebruik van MkDocs Material om
alle documentatie te publiceren. Bij gebruik van plaatjes is het fijn als de bron daarvan ook
onderdeel is van dit project ... en bij voorkeur in een open formaat. Dat betekent dat deze
aangepast en bijgewerkt kunnen worden zonder kosten te maken voor tools. Nogmaals: bij voorkeur.
- Zorg dat bijdragen cross-platform uitwisselbaar zijn: Windows, Mac, Linux.
- Zorg dat code en documentatie compleet is en voldoet aan de [styleguides](#styleguides).
- Maak issues aan voor elke grote wijziging en verbetering die je graag wilt maken. Bespreek de
dingen transparant en vraag community feedback.
- Probeer bijdragen compact en klein te houden; dat draagt bij aan het behoud van overzicht en
wijzigingen.
- Wees open naar nieuwe mensen en moedig nieuwe bijdragen aan van alle achtergronden.
- Issues behoren van een passend label te zijn voorzien:
- `Bug` betekent een urgent probleem in de community of in de documentatie
- `Enhancement` betekent een bijdrage voor uitbreiding
- `Question` betekent een vraag
## Ik heb een vraag
> Als je een vraag wilt stellen, gaan we ervan uit dat je de beschikbare
> [documentatie](https://ospo-nl.github.io/kennisbank/) hebt gelezen.
Voordat je een vraag stelt, kun je het beste zoeken naar bestaande
[issues](https://github.com/ospo-nl/kennisbank/issues) die je kunnen helpen. Als u een geschikt
probleem hebt gevonden en nog steeds verduidelijking nodig heeft, kunt u uw vraag in dit nummer
schrijven. Het is ook raadzaam om eerst op internet naar antwoorden te zoeken.
Als je dan toch de behoefte voelt om een vraag te stellen en verduidelijking nodig hebt, raden we
het volgende aan:
- Open een [issue](https://github.com/ospo-nl/kennisbank/issues/new).
- Geef het issue een passend label (zie [verwachtingen](#verwachtingen)).
- Geef zoveel mogelijk context over waar je tegenaan loopt.
- Indien van toepassing: Lever technische afhankelijkheden die relevant lijken.
We zullen het probleem dan zo snel mogelijk in behandeling nemen.
## Ik wil bijdragen
> **Juridische mededeling**
>
> Wanneer u bijdraagt aan dit project, moet u ermee instemmen dat u 100% van de inhoud hebt
> geschreven, dat u over de benodigde rechten op de inhoud beschikt en dat de inhoud die u bijdraagt
> onder de projectlicentie mag worden geleverd.
### Issues melden
#### Voordat u een issue indient
Een goed issue zou er niet voor moeten zorgen dat anderen u moeten achtervolgen voor meer
informatie. Daarom vragen we u om dit zorgvuldig te onderzoeken, informatie te verzamelen en het
probleem in detail te beschrijven in uw melding.
- Zorg ervoor dat u de nieuwste versie gebruikt.
- Lees de [documentatie](https://ospo-nl.github.io/kennisbank/) aandachtig door en ontdek of de
functionaliteit al wordt gedekt, misschien door een individuele configuratie.
- Voer een [zoekopdracht](https://github.com/ospo-nl/kennisbank/issues) uit om te zien of de
verbetering al is voorgesteld. Als dit het geval is, voeg dan een opmerking toe aan de bestaande
uitgave in plaats van een nieuwe te openen.
Voor dit moment is er alleen documentatie en zijn verdere voorbereidingen niet nodig. Mocht er ooit
tools en software componenten opgeleverd worden, dan is het van belang om de details daarvan ook
duidelijk te melden en te onderzoeken of het daadwerkelijk een probleem met die software is of dat
het wellicht toch een fout in uw omgeving is.
#### Hoe dien ik een goed issue in?
> U mag beveiligingsgerelateerde problemen, kwetsbaarheden of issues, inclusief gevoelige
> informatie, nooit melden aan de issue tracker of elders in het openbaar. In plaats daarvan moeten
> gevoelige bugs per e-mail naar <TODO> worden gestuurd.
We gebruiken GitHub-problemen om issue en fouten op te sporen. Als u een probleem met het project
tegenkomt:
- Open een [issue](https://github.com/ospo-nl/kennisbank/issues/new). (Omdat we op dit moment niet
zeker weten of het een fout is of niet, vragen we je om nog niet over een fout te praten en het
probleem niet te labelen.)
- Leg zo duidelijk mogelijk uit wat u verwacht of wens en geef suggesties voor invulling daarvan.
- Geef de informatie op die u in het vorige gedeelte hebt verzameld.
Zodra het is ingediend:
- Het projectteam zal het probleem dienovereenkomstig labelen.
- Een teamlid zal proberen het issue te begrijpen en op te volgen.
#### Meer hulp
Hier zijn een paar vriendelijke (maar Engelse) handleidingen voor meer hulp en achtergronden: [First
Timers Only](http://www.firsttimersonly.com/) en [Make A Pull Request](http://makeapullrequest.com/)
### Verbeteringen voorstellen
Deze sectie begeleidt u bij het indienen van een verbeteringssuggestie voor OSPO-NL, **inclusief
volledig nieuwe functies en kleine verbeteringen aan bestaande functionaliteit**. Door deze
richtlijnen te volgen, kunnen beheerders en de community uw suggestie begrijpen en gerelateerde
suggesties vinden.
#### Voordat u een verbetering indient
- Zorg ervoor dat u de nieuwste versie gebruikt.
- Lees de [documentatie](https://ospo-nl.github.io/kennisbank/) aandachtig door en ontdek of de
functionaliteit al wordt gedekt, misschien door een individuele configuratie.
- Voer een [zoekopdracht](https://github.com/ospo-nl/kennisbank/issues) uit om te zien of de
verbetering al is voorgesteld. Als dit het geval is, voeg dan een opmerking toe aan de bestaande
uitgave in plaats van een nieuwe te openen.
- Ga na of uw idee past binnen de reikwijdte en doelstellingen van het project. Het is aan u om een
sterk pleidooi te houden om de ontwikkelaars van het project te overtuigen van de voordelen van
deze functie. Houd er rekening mee dat we functies willen die nuttig zijn voor de meerderheid van
onze gebruikers en niet slechts voor een kleine subgroep. Als u zich slechts op een minderheid van
gebruikers richt, overweeg dan om een bibliotheek met add-ons/plug-ins te schrijven.
#### Hoe dien ik een goede verbeteringssuggestie in?
Suggesties voor verbeteringen worden bijgehouden als [GitHub
issues](https://github.com/ospo-nl/kennisbank/issues).
- Gebruik een **duidelijke en beschrijvende titel** voor het probleem om de suggestie te
identificeren.
- Geef een stapsgewijze beschrijving van de voorgestelde verbetering met zoveel mogelijk details.
- Beschrijf het huidige gedrag en leg uit welk gedrag je in plaats daarvan verwachtte te zien en
waarom. Op dit punt kunt u ook zien welke alternatieven niet voor u werken.
- Misschien wilt u schermafbeeldingen en geanimeerde GIF's toevoegen die u helpen de stappen te
demonstreren of aan te geven op welk onderdeel de suggestie betrekking heeft. U kunt deze tool
gebruiken om GIF's op macOS en Windows op te nemen, en deze tool of deze tool op Linux.
- Leg uit waarom deze verbetering nuttig zou zijn voor de meeste gebruikers van OSPO-NL. Misschien
wil je ook wijzen op de andere projecten die het beter hebben opgelost en die als inspiratie
kunnen dienen.
## Review proces
Om wijzigingen goed te kunnen beheren, volgen en uit te leggen, volgen we een eenvoudig proces van
review en Pull Requests (PRs).
- Wijzigingen wordt nooit direct op de `main` branch gedaan, maar altijd in een 'feature' branch.
- Maak een Pull Request aan zodra je klaar bent. Of maak gelijk een Draft Pull Request aan nadat u
uw feature branch hebt aangemaakt. Zodra uw wijzigingen klaar zijn voor review, wijzigt u uw Draft
PR naar 'Ready for Review'.
- Een teamlid reviewt de wijzigingen in het Pull Request en geeft commentaar en/of goedkeuring
(Approve).
- Na goedkeuring kan het Pull Request gemerged worden. Hiervoor wordt standaard 'Squash & Merge'
gebruikt. In geval dat de PR door een teamlid is ingediend, reviewt een ander teamlid de PR maar
wordt de merge overgelaten aan de auteur van de PR.
- Na de merge dienen bijbehorende issues bijgewerkt te worden zodat deze niet onnodig open blijven
staan ofwel beantwoord worden.
## Styleguides
### Markdown
Alle documentatie moet 'machine-readable' zijn en tegelijk ook makkelijk leesbaar en onderhoudbaar
voor mensen. Daarom maken we gebruik van **Markdown**. Zie ook [GitHub
Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
en de algemene [Markdown handleiding](https://www.markdownguide.org/basic-syntax/) (EN) (of zelfs de
originele [documentatie](https://daringfireball.net/projects/markdown/syntax)). De documentatie van
het gebruikte [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/) thema
benoemt de opmaak die extra wordt ondersteunt door het thema.
Alinea's worden op of binnen **100 karakters** afgekapt om versiebeheer per regel beheersbaar te
maken. Dit kan automatisch worden afgedwongen in tooling, bijv. [Rewrap in
VSCode](https://stkb.github.io/Rewrap/) (keyboard shortcut: `alt+Q`).
### Bestandsnamen
Alle bestandsnamen, zowel van bestanden (files) als van mappen (folders), komen terug in de URL van
de gepubliceerde documentatie ... en spaties zijn niet zo standaard voor URLs. Daarom worden er GEEN
spaties gebruikt in bestandsnamen. Deze worden vervangen door `_`, underscores. In het genereren van
de documentatie worden deze netjes vervangen door spaties zodat de layout er wel mooi en netjes uit
ziet! :muscle:
### Regeleinden
Er zijn meerdere manieren om regeleinden (Engels: line endings) te codificeren in bestanden. Voor
dit project horen die `LF` te zijn, zoals gebruikelijk voor de meeste projecten. Hiermee is
gegarandeerd dat op Linux, Windows en Mac OSX bestanden op dezelfde wijze worden gepresenteerd en
Pull Requests gemakkelijk zijn. Lokaal uitchecken met CRLF (in Windows) en commits met LF is
uiteraard toegestaan .. als het resultaat maar met LF in GitHub terecht komt :smile:
Zie ook [Blog: Mind the End of Your
Line](https://adaptivepatchwork.com/2012/03/01/mind-the-end-of-your-line/) en [GitHub Help on Line
Endings](https://docs.github.com/en/get-started/getting-started-with-git/configuring-git-to-handle-line-endings).
## Community
De OSPO-NL Community is nog in oprichting. Voor dit moment zijn er nog geen officiële kanalen en
samenwerkingsverbanden anders dan actief betrokken personen. Zie ook meer in de [over
ons](https://ospo-nl.github.io/kennisbank/Over_ons).
## Attribution
Een eigen CONTRIBUTING maken is niet echt moeilijk ... en toch ook weer wel. Inspiratie voor deze
variant komt van een
[template](https://github.com/nayafia/contributing-template/blob/HEAD/CONTRIBUTING-template.md) en
**contributing-gen**. [Genereer zelf](https://github.com/bttger/contributing-gen) (incl. CODE OF
CONDUCT) !
Voorbeeld: de CONTRIBUTING.md van developer.overheid.nl:
./CONTRIBUTING.md
# Bijdragerichtlijnen
:::info[Naar het artikel over CONTRIBUTING.md]
Raadpleeg [ons artikel over CONTRIBUTING.md](https://developer.overheid.nl/kennisbank/leidraad/open-source/standaarden/contributing-md) voor meer info over het zelf opstellen van bijdragerichtlijnen.
:::
## Introductie
Om te beginnen, hartelijk dank voor je interesse om bij te dragen aan ons gezamenlijke Developer Portal voor de hele Nederlandse overheid! Door onze ervaringen te delen, helpen we anderen om beter onderbouwde keuzes te maken. Omdat wij willen voorkomen dat we standaarden of projecten uit specifieke organisaties een voorkeursbehandeling geven, ontvangen we graag thema's en documentatie van zoveel mogelijk organisaties binnen de overheid.
## Dit portaal
Software bouwen voor de overheid brengt specifieke uitdagingen met zich mee. Dit portaal helpt je om te voldoen aan overheidspecifieke eisen, zoals securitystandaarden en toegankelijkheidsrichtlijnen. Daarnaast vind je hier informatie over beschikbare Open Source-projecten en hoe je deze kunt inzetten.
## Hoe je kunt bijdragen
Alle artikelen in onze kennisbank zijn geschreven in de `.md` of `.mdx` extensie en dus eenvoudig aan te passen.
Je kunt bijdragen op de volgende manieren:
- Draag een **artikelonderwerp aan**. Dien een [issue](https://github.com/developer-overheid-nl/don-site/issues/new) in met jouw idee.
- Zelf een **artikel bijdragen**. Dit doe je door een [fork aan te maken](https://github.com/developer-overheid-nl/don-site/fork) en deze vervolgens aan te bieden als [pull request](https://github.com/developer-overheid-nl/don-site/compare).
- Voeg een [**API**](https://apis.developer.overheid.nl/apis/toevoegen) toe aan ons API register.
- Voeg een [**gitaccount**](https://oss.developer.overheid.nl/toevoegen/repository) toe aan ons OSS register.
- Door vragen te stellen of je te **mengen in discussies** in ons [Slack kanaal](https://codefornl.slack.com/archives/CFV4B3XE2).
- **Bugs** te melden. Dien een [issue](https://github.com/developer-overheid-nl/don-site/issues/new) in.
- Door ideeën aan te dragen om ons design, UX of accessibility te verbeteren. Je doet dit door een [issue in te schieten](https://github.com/developer-overheid-nl/don-site/issues/new).
## Labels voor issues
Om issues beter te organiseren, gebruiken we labels. Voeg bij het indienen van een issue een passend label toe, zodat het sneller de juiste aandacht krijgt:
- `content` → Voor voorstellen of wijzigingen aan artikelen.
- `bug` → Voor het melden van fouten of problemen.
- `ux` → Voor ideeën en verbeteringen rondom design, gebruikerservaring en toegankelijkheid.
- `enhancement` → Voor het voorstellen van nieuwe features of verbeteringen aan bestaande functionaliteit.
Een volledig overzicht van beschikbare labels vind je in onze [GitHub repository](https://github.com/developer-overheid-nl/don-site/labels).
## Voordat je begint
Voor je aan de gang gaat zouden we je willen vragen de volgende punten af te vinken:
- Heeft iemand anders al eens een soortgelijk issue ingediend? Check dit in de [backlog](https://github.com/developer-overheid-nl/don-site/issues).
- Ben je van plan zelf een feature te bouwen? Neem dan om af te stemmen eerst contact met ons op via [Slack](https://codefornl.slack.com/archives/CFV4B3XE2) of [e-mail](mailto:developer.overheid@geonovum.nl).
## Coderichtlijnen
Op dit moment hanteren we in onze codebases (nog) geen strikte voorschriften mbt het opleveren van code. We gaan er vanuit dat als iets met zorg is gebouwd er goed is nagedacht over de opzet en de schrijfwijze. Mocht je vragen hebben over hoe je iets dient op te leveren dan kun je je vraag stellen in ons [Slackkanaal](https://codefornl.slack.com/archives/CFV4B3XE2).
## Aanbieden pull request
Wanneer je pull request wordt gemerged in de `main` branch, squashen we alle commits tot één commit met een passende naam. Je hoeft je dus niet druk te maken dat de namen van je commits allemaal even eloquent hoeven te zijn.
## Opzetten ontwikkelomgeving
Check onze [README.md](https://github.com/developer-overheid-nl/don-site/blob/main/README.md).
## Gedragscode
Check onze [CODE_OF_CONDUCT.md](https://github.com/developer-overheid-nl/don-site/blob/main/CODE_OF_CONDUCT.md).
## Juridisch
Dit project heeft een EUPL (European Union Public License) licentie. Dit betekent dat de volgende punten van toepassing zijn op je bijdrage:
1. Je bijdrage valt **automatisch onder de EUPL**.
De EUPL bevat een copyleft-bepaling, wat betekent dat alle afgeleide werken ook onder de EUPL (of een compatibele licentie) moeten blijven.
Dit voorkomt dat je bijdrage later wordt omgezet naar een gesloten, propriëtair product.
2. Je **behoudt** het **auteursrecht** op je code.
Jij blijft juridisch eigenaar van je eigen bijdrage.
Maar door bij te dragen, geef je anderen het recht om jouw code te gebruiken, wijzigen en verspreiden onder de voorwaarden van de EUPL.
3. Iedereen mag je code **gebruiken** en **aanpassen**.
De EUPL staat toe dat anderen jouw code kopiëren, verspreiden en aanpassen, zolang ze zich aan de licentievoorwaarden houden.
Dit betekent ook dat verbeteringen en aanpassingen aan jouw code weer terug kunnen vloeien in de community.
4. **Compatibiliteit** met andere licenties.
De EUPL is compatibel met een aantal andere open source-licenties, zoals de GPL en de MPL. Dit betekent dat jouw code onder bepaalde voorwaarden ook in projecten met die licenties kan worden gebruikt.
5. Je hebt recht op **erkenning**.
De licentie vereist dat jouw auteurschap erkend blijft. Anderen mogen je code dus niet zomaar zonder naamsvermelding overnemen.
Als je jezelf, nadat je een bijdrage hebt gedaan, wilt vereeuwigen in onze codebase nodigen we je uit om jezelf aan onze [AUTHORS.md](https://github.com/developer-overheid-nl/don-site/blob/main/AUTHORS.md) toe te voegen.
## Bestuur
Voor meer informatie over de financiering en organisatie van dit project, zie onze [GOVERNANCE.md](https://github.com/developer-overheid-nl/don-site/blob/main/GOVERNANCE.md).
## Contact
Check onze [README.md](https://github.com/developer-overheid-nl/don-site/blob/main/README.md#contact) onder het kopje contact.