Skip to content

Commit

Permalink
Merge pull request #49 from MinBZK/main
Browse files Browse the repository at this point in the history 
update develop branch from main
  • Loading branch information
@ruthkoole
ruthkoole authored Feb 19, 2024
2 parents 846cfdd + 10566d3 commit 6ccc082
Show file tree
Hide file tree
Showing 75 changed files with 1,082 additions and 939 deletions.
8 changes: 2 additions & 6 deletions .github/CODEOWNERS
View file
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,16 @@

# These owners will be the default owners for everything in
# the repo. Unless a later match takes precedence,
# @BartdeVisser @IsabelBarbera @HaitskevdLinde @giuliaboss @ruthkoole @jaspervanderheide and @MarjoleinKortemann will be requested for
# @IlseZandbergen @cloevgeest @Jellie2022 @BartdeVisser @IsabelBarbera @HaitskevdLinde @giuliaboss @ruthkoole @jaspervanderheide and @MarjoleinKortemann will be requested for
# review when someone opens a pull request.
* @BartdeVisser @IsabelBarbera @HaitskevdLinde @giuliaboss @ruthkoole @jaspervanderheide @MarjoleinKortemann
* @IlseZandbergen @cloevgeest @Jellie2022 @BartdeVisser @IsabelBarbera @HaitskevdLinde @giuliaboss @ruthkoole @jaspervanderheide @MarjoleinKortemann

# Order is important; the last matching pattern takes the most
# precedence. When someone opens a pull request that only
# modifies JS files, only @js-owner and not the global
# owner(s) will be requested for a review.
# *.js @js-owner # Remove '#' where necessary to activate it

# You can also use email addresses if you prefer. They'll be
# used to look up users just like we do for commit author
# emails.
# *.go [email protected] # Remove '#' where necessary to activate it

# Teams can be specified as code owners as well. Teams should
# be identified in the format @org/team-name. Teams must have
Expand Down
93 changes: 26 additions & 67 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,80 +1,39 @@
# Algoritmekader
We ontwikkelen het Algoritmekader op een open manier via Github. Bekijk [de ontwikkelomgeving van het Algoritmekader](https://minbzk.github.io/Algoritmekader/).

**Welkom op de Github repo voor het algoritmekader!**
**Dit is de Github repo voor het Algoritmekader**
Op deze pagina lees je hoe je kunt bijdragen aan de ontwikkeling van het Algoritmekader. Boven deze tekst vind je de bestanden voor het kader. We gebruiken Markdown en Mkdocs. Meer daarover lees je onder punt 5.

## Algoritmekader
## Hoe kun je bijdragen?
Dat kan op verschillende manieren. Kijk welke manier jou het beste past.
1 t/m 5 zijn geschikte manieren voor gebruikers die nog niet zo bekend zijn met Github.
5 en 6 Geven input voor ervaren Github gebruikers, die op de voor hen bekende manieren een bijdrage kunnen leveren.

Het ministerie van BZK gaat aan de slag met een Algoritmekader. Het doel daarvan is om overheden op praktische wijze te ondersteunen, zodat zij op een wettige en ethisch verantwoorde wijze algoritmes en AI-systemen gebruiken.
### 1. Sluit je aan bij een werkgroep ###
Regelmatig starten er nieuwe werkgroepen op bouwblokken of thema's. Deelname kost gemiddeld 3-4 uur per week. Wil je op een van de onderwerpen meewerken? Stuur dan een bericht naar [email protected] 

Belangrijk uitgangspunt bij de ontwikkeling van het kader is om zoveel mogelijk gebruik te maken van de kennis en kunde die er al is. En nadenken over hoe bestaande informatie geordend kan worden. Het kader kan daar een handig hulpmiddel voor zijn. Het is belangrijk om bij de inzet van algoritmes in alle fasen te weten welke stappen van belang zijn. De verschillende stappen zijn een goed uitgangspunt voor de ontwikkeling van het Algoritmekader.
### 2. Neem deel aan een sprintreview ###
We werken in sprints van 3 of 4 weken, gevolgd door een open online review. Zo blijf je op de hoogte en kun je een bijdrage leveren. [Bekijk de agenda op Algoritmes Pleio](https://algoritmes.pleio.nl/events) voor de komende bijeenkomsten.

## Disclaimer
Het Algoritmekader is nog volop in ontwikkeling. Op deze Github willen we vooral aan de slag gaan op een open en transparante wijze. Het is dus niet definitief. Dat betekent dat er dingen opstaan die niet af zijn en soms zelfs fout. Mocht er iets niet kloppen, laat het ons weten.
### 3. Stuur een e-mail naar [[email protected]](mailto:[email protected])
1. Stuur ons je vraag of opmerking, met een duidelijke toelichting. We reageren binnen enkele dagen op je mail.
2. Het team van het Algoritmekader pakt jouw issue op en neemt mogelijk contact op voor verduidelijking of oplossing.

## Hoe kan je bijdragen aan de ontwikkeling van het algoritmekader?
### 4. Maak een issue aan
1. Via [Issues](https://github.com/MinBZK/Algoritmekader/issues) kan je bestaande issues bekijken of een nieuwe aanmaken.
2. Gebruik daarvoor de knop `new issue`.
3. Schrijf je vraag of opmerking is en geef een heldere toelichting.
4. Anderen kunnen comments toevoegen aan jouw issue.
5. Het team van het Algoritmekader pakt jouw issue op en neemt mogelijk contact op voor verduidelijking of oplossing.

We ontwikkelen het algoritmekader open source via GitHub. Voor de documentatie maken we gebruik van [Markdown](https://www.markdownguide.org/basic-syntax/) bestanden. Dit bestandsformaat wordt door veel verschillende tools ondersteund, en maakt het eenvoudig versiebeheer op het algoritmekader toe te passen. Hierdoor hebben we grip op reviews en verschillende versies van het kader.
### 5. Stuur een *pull request*
Kun je niet uit de voeten met de issues? Bijvoorbeeld omdat je verschillende wijzigingsvoorstellen wilt doen. We houden het aantal collaborators zeer beperkt. Gebruik bijvoorbeeld [Fork en doe een Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks). Het team van Algoritmekader bekijkt daarna jouw aanpassingen en kan bij akkoord jouw aanpassingen *mergen*. Er zijn ook andere manieren om een pull request te doen. [Meer daarover](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).

Vooralsnog maken we tijdens de ontwikkelfase gebruik van [mkdocs](https://www.mkdocs.org/) en [material for mkdocs](https://squidfunk.github.io/mkdocs-material/) om de documentatie inzichtelijk te maken op een website. Hiermee faciliteren we ook al in de ontwikkelfase interactiviteit en flexibiliteit. Uiteindelijk is de bedoeling dat het algoritmekader onderdeel wordt van een bestaande overheidswebsite zoals [Digitale Overheid](www.digitaleoverheid.nl).

Als je wilt bijdragen aan het algoritmekader, is dat voor ons het makkelijkst via GitHub en de markdown bestanden. Hieronder volgen een aantal mogelijkheden hoe je dat kan doen:

### Heb je een fout gevonden? Of heb je een vraag, opmerking of een andere aanbeveling? Maak een issue aan!
1. Via [Issues](https://github.com/MinBZK/Algoritmekader/issues) kan je bestaande issues bekijken of een nieuwe *issue* aanmaken.
2. Via de knop `new issue` kan je een nieuw issue aanmaken.
3. Voeg hier toe wat je vraag of opmerking is en geef een uitgebreide toelichting, zodat we duidelijk begrijpen wat jouw vraag of opmerking is.
4. Het is vervolgens mogelijk om een discussie te voeren over het door jou aangemaakte issue door comments toe te voegen.
5. Het team van het algoritmekader gaat aan de slag met jouw issue en zal mogelijk contact opnemen voor een verduidelijking of oplossing.

### Ben je collaborator? Maak gebruik van branches!
Indien je door het team van algoritmekader bent toegevoegd als *collaborator*, kan je eenvoudiger aanpassingen doen aan het algoritmekader. Hieronder volgt een instructie hoe dat werkt.

#### Branches
We werken met verschillende *branches*, waardoor we vrij kunnen ontwikkelen, zonder dat dat gelijk invloed heeft op de versie in *productie*. Linksbovenin zie je de verschillende branches die er zijn (zie afbeelding voor een voorbeeld). De *main* branch is de versie van het algoritmekader die gekoppeld is aan https://minbzk.github.io/Algoritmekader/.

![afbeelding](https://github.com/MinBZK/Algoritmekader/assets/71120805/36ebc0a2-acf0-4404-aad6-59cbd0bc3243)

De *main* branch wordt standaard weergegeven en kan alleen aangepast worden na goedkeuring door het team van het algoritmekader. Als je wilt bijdragen moet je dus eerst werken in een andere branch.

1. Je kan van branch wisselen door linksboven op de huidige branch te klikken en vervolgens jouw branch waarin je wilt werken te selecteren. Je kan eventueel ook een nieuwe branch maken door de naam van de branch in te typen. Kies een logische naam, bijvoorbeeld `werkgroep-inkoop`.
2. Bewerk de bestanden door in de mappenstructuur (de `docs` map) te navigeren naar het juiste bestand, en rechtsboven op de `edit` knop te klikken (het potloodje). Je kan ook nieuwe bestanden toevoegen door rechtsboven op `add file` te klikken.
3. Wanneer je je aanpassingen wilt opslaan, klik je rechtsboven op de `commit changes` knop. Je wordt nu gevraagd om een *commit message* mee te geven. Geef hier een korte en duidelijke omschrijving van jouw aanpassing, bijvoorbeeld `hoofdstuk over normen toegevoegd` of `typo's verbeterd`. Indien je nog niet van branch gewisseld was, wordt er gevraagd om alsnog een nieuwe branch te maken. Klik vervolgens op `commit changes`.
4. Bewerk meer bestanden op dezelfde manier.
5. Wanneer je tevreden bent over jouw aanpassingen, en deze wilt samenvoegen met de *main* branch zodat zichtbaar worden op https://minbzk.github.io/Algoritmekader/, kan je een *pull request* aanmaken. Bovenaan de repository staat nu een bericht, bijvoorbeeld: `werkgroep-inkoop had recent pushes x minutes ago` met vervolgens een knop `compare & pull request`. Klik op `compare & pull request`. Je komt nu op een pagina waar je een titel een een beschrijving mee kan geven aan je pull request. Vul dit in en klik vervolgens op `create pull request`.
6. Je komt nu op een pagina waar je de verschillen tussen jouw versie en de andere versie kan zien. Het is ook mogelijk een discussie te voeren over de door jou aangedragen wijzigingen.
7. Het team van het algoritmekader gaat nu jouw wijzigingen reviewen en indien akkoord worden jouw aanpassingen gemergd met de *main* branch. Let op! Je kan zelf nooit je eigen pull request mergen, dit moet worden gedaan na review door een collega.

### Met *fork* en een *pull request*
Indien je niet bent toegevoegd als collaborator, kan je toch bijdragen aan het algoritmekader. Dit werkt door zelf een kopie (*fork*) te maken van de repository op je eigen account.
1. Maak een *fork* van de repository door rechtsboven op de knop `fork` te klikken. Je hebt nu een kopie van de repository gemaakt op je eigen account.
2. Je kan de bestanden nu bewerken door in de mappenstructuur (de `docs` map) te navigeren naar het juiste bestand, en rechtsboven op de `edit` knop te klikken (het potloodje). Mocht je nog geen fork hebben gemaakt, dan kan wordt hier eerst gevraagd een fork te maken. Je kan ook nieuwe bestanden toevoegen door rechtsboven op `add file` te klikken.
3. Wanneer je je aanpassingen wilt opslaan, klik je rechtsboven op de `commit changes` knop. Je wordt nu gevraagd om een *commit message* mee te geven. Geef hier een korte en duidelijke omschrijving van jouw aanpassing, bijvoorbeeld `hoofdstuk over normen toegevoegd` of `typo's verbeterd`.
4. Je komt nu gelijk op een pagina waar je jouw aanpassingen kan vergelijken. Wanneer je tevreden bent over je aanpassingen, maak je een *pull request* aan door op de knop `Create pull request`te klikken.
5. Je kan nu nog meer aanpassingen doen aan andere bestanden.
6. Wanneer je tevreden bent over jouw aanpassingen, en deze wilt samenvoegen met de versie in productie kan je een *pull request* aanmaken. Bovenaan jouw versie van de repository staat nu een bericht: `jouw branche is x commits ahead of ...` met vervolgens een knop `contribute`. Klik op `contribute` en vervolgens op `open pull request`. Je komt nu op een pagina waar je de verschillen tussen jouw versie en de andere versie kan zien. Check nogmaals of je tevreden bent en klik vervolgens op `open pull request`.
7. Het team van algoritmekader bekijkt nu jouw aanpassingen en zal indien akkoord jouw aanpassingen *mergen*.
We werken met [Markdown](https://www.markdownguide.org/basic-syntax/) bestanden. Dit bestandsformaat wordt door veel verschillende tools ondersteund, en maakt het eenvoudig versiebeheer toe te passen. Tijdens de ontwikkelfase gebruiken we [mkdocs](https://www.mkdocs.org/) en [material for mkdocs](https://squidfunk.github.io/mkdocs-material/) voor de presentatie op [de ontwikkelomgeving](https://minbzk.github.io/Algoritmekader/). Zo werken we direct aan de interactiviteit en flexibiliteit van het kader. Uiteindelijk landt het Algoritmekader op een bestaande overheidswebsite zoals [Digitale Overheid](www.digitaleoverheid.nl).

### Lokaal draaien van de website (via de command line)
Je kan de site van het algoritmekader ook lokaal draaien en gelijk je aanpassingen bekijken. Dit werkt als volgt:
1. Maak een fork van de repository als je die nog niet hebt (indien je collaborator/code owner bent is het maken van een fork niet nodig)
2. Clone de repository op je lokale machine met behulp van `git clone https://github.com/github-username/repository-name.git`
3. Check de nodige dependencies via het command `mkdocs get-deps` en zorg dat deze dependencies lokaal geinstalleerd zijn (bijvoorbeeld `pip install mkdocs`)
4. Run vervolgens `mkdocs serve` om de website lokaal te draaien.
5. In de terminal staat nu `serving on ...` Klik op de link om de website lokaal te tonen.

#### Lokaal aanpassingen doen en pull request maken
1. Maak een nieuwe branch aan door `git checkout -b branch-name`
2. Doe de aanpassingen die je wilt doen
3. Voeg de bestandne die je hebt aangepast toe met behulp van `git add filepaden-van-aangepaste-bestanden` (tip gebruik eerst `git status`)
4. Commit de aanpassingen met behulp van `git commit -m "Korte toelichting bij de commit"`
5. Wanneer je de website met jouw aanpassingen lokaal wilt draaien kan dat via het command `mkdocs serve`
6. Indien je je aanpassingen wilt mergen met de main repository, push je de aanpassingen naar de remote met behulp van `git push origin branch-name`
7. Maak een pull-request aan
8. Het team van het algoritmekader gaat nu jouw wijzigingen reviewen en indien akkoord worden jouw aanpassingen gemergd met de *main* branch.

### Iets aanpassen in de navigatie van de website?
We maken gebruik van [mkdocs](https://www.mkdocs.org/) en [material for mkdocs](https://squidfunk.github.io/mkdocs-material/) om de documentatie inzichtelijk te maken op een website. In het bestand [mkdocs.yml](https://github.com/MinBZK/Algoritmekader/blob/main/mkdocs.yml) bestand staan de settings voor deze website. In principe hoef je hier niets aan aan te passen.
### 6. Iets aanpassen in de navigatie van de website?
We maken gebruik van [mkdocs](https://www.mkdocs.org/) en [material for mkdocs](https://squidfunk.github.io/mkdocs-material/) om de documentatie inzichtelijk te maken op een website. In het bestand [mkdocs.yml](https://github.com/MinBZK/Algoritmekader/blob/main/mkdocs.yml) bestand staan de settings voor deze website. In principe hoef je hier niets aan aan te passen.
Onderdeel van deze settings is de navigatie voor de site (welke kopjes zijn zichtbaar, en welke kopjes vallen daaronder). Dit staat in de `nav:` sectie. Indien je een kopje wilt toevoegen, kan dat in deze sectie.

## Vragen?
Maak een [Issue](https://github.com/MinBZK/Algoritmekader/issues) aan op GitHub. Kom je er niet uit, dan kan je altijd mailen naar [email protected]
Maak een [Issue](https://github.com/MinBZK/Algoritmekader/issues) aan op GitHub. Of mail [[email protected]](mailto:[email protected])
2 changes: 0 additions & 2 deletions docs/bouwblokken/conformiteitsbeoordeling/audit.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,14 +38,12 @@ Onderstaand een overzicht van de minimale vereisten die volgen uit geldende wet-

| **Norm** | **Uitleg** | **Bron** |
|-----------------------------------|------------------------------------------|----------|
| [Norm 1](../../normen/transparantie/norm1.md) | Korte uitleg over norm 1 | |
| Norm 2 | Korte uitleg over norm 2 | |

=== "Hoog risico"

| **Norm** | **Uitleg** | **Bron** |
|-----------------------------------|------------------------------------------|----------|
| [Norm 1](../../normen/transparantie/norm1.md) | Korte uitleg over norm 1 | |
| Norm 2 | Korte uitleg over norm 2 | |
| Norm 3 | Korte uitleg over norm 3 | |
| Norm 4 | Korte uitleg over norm 4 | |
Expand Down
2 changes: 0 additions & 2 deletions docs/bouwblokken/conformiteitsbeoordeling/toezicht.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,14 +59,12 @@ Onderstaand een overzicht van de minimale vereisten die volgen uit geldende wet-
=== "Laag risico"
| **Norm** | **Uitleg** | **Bron** |
|-----------------------------------|------------------------------------------|----------|
| [Norm 1](../../normen/transparantie/norm1.md) | Korte uitleg over norm 1 | |
| Norm 2 | Korte uitleg over norm 2 | |

=== "Hoog risico"

| **Norm** | **Uitleg** | **Bron** |
|-----------------------------------|------------------------------------------|----------|
| [Norm 1](../../normen/transparantie/norm1.md) | Korte uitleg over norm 1 | |
| Norm 2 | Korte uitleg over norm 2 | |
| Norm 3 | Korte uitleg over norm 3 | |
| Norm 4 | Korte uitleg over norm 4 | |
Expand Down
3 changes: 2 additions & 1 deletion docs/bouwblokken/fundamentele rechten/non-discriminatie.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@ Onderstaand een overzicht van de minimale vereisten die volgen uit geldende wet-

| **Norm** | **Uitleg** | **Bron** |
|-----------------------------------|------------------------------------------|----------|
| [Norm 1](../../normen/transparantie/norm1.md) | Korte uitleg over norm 1 | |
| Norm 2 | Korte uitleg over norm 2 | |

=== "Hoog risico"
Expand Down Expand Up @@ -95,3 +94,5 @@ Overzicht van welke rollen belangrijk zijn te betrekken bij dit bouwblok.
* In alle gevallen moeten de selectiecriteria binnen een risicoprofiel samen voldoende relevant en objectief (geschikt) zijn om op een effectieve wijze bij te dragen aan de verwezenlijking van het nagestreefde legitieme doel;
* Het gebruik van ras of nationaliteit als selectiecriterium binnen een risicoprofiel moet daarnaast noodzakelijk zijn om het gewenste doel tebereiken.
* Selectiebeslissingen moeten te allen tijde uitlegbaar zijn.
## Mogelijke hulpmiddelen en methoden
* [Fairness Handbook](https://amsterdamintelligence.com/resources/the-fairness-handbook)
2 changes: 0 additions & 2 deletions docs/bouwblokken/inkoop/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,14 +35,12 @@ Onderstaand een overzicht van de minimale vereisten die volgen uit geldende wet-

| **Norm** | **Uitleg** | **Bron** |
|-----------------------------------|------------------------------------------|----------|
| [Norm 1](../../normen/transparantie/norm1.md) | Korte uitleg over norm 1 | |
| Norm 2 | Korte uitleg over norm 2 | |

=== "Hoog risico"

| **Norm** | **Uitleg** | **Bron** |
|-----------------------------------|------------------------------------------|----------|
| [Norm 1](../../normen/transparantie/norm1.md) | Korte uitleg over norm 1 | |
| Norm 2 | Korte uitleg over norm 2 | |
| Norm 3 | Korte uitleg over norm 3 | |
| Norm 4 | Korte uitleg over norm 4 | |
Expand Down
Loading

0 comments on commit 6ccc082

Please sign in to comment.