GitHub - Direct meewerken in de repository

Direct meewerken via GitHub is handig als je regelmatig pagina's wilt corrigeren, nieuwe Markdown-bestanden wilt aanmaken of met de CircusWiki-vault wilt werken in een editor zoals Obsidian.

Als je alleen een spel, een methode, een PDF, een link of een correctie wilt bijdragen, is de eenvoudigere weg meestal beter:

Terug naar Meedoen

Wat je nodig hebt¶

• een gratis GitHub-account: https://github.com/join
• optioneel GitHub Desktop: https://desktop.github.com/
• een teksteditor voor Markdown-bestanden, bijvoorbeeld Obsidian, VS Code of een eenvoudige editor

GitHub Desktop is niet verplicht, maar voor veel mensen eenvoudiger dan de commandoregel.

Repository vinden¶

Het openbare repository staat hier:

https://github.com/nica-ev/circuswiki

Daar staan de eigenlijke Markdown-bestanden, afbeeldingen, vertalingen en tools waaruit de website wordt opgebouwd.

Werkwijze in het kort¶

De typische gang van zaken is:

1. Repository op GitHub forken.
2. Je kopie naar je eigen computer klonen.
3. Wijzigingen aanbrengen in een nieuwe branch.
4. Bestanden bewerken of nieuwe Markdown-bestanden aanmaken.
5. Wijzigingen committen.
6. Branch naar GitHub uploaden.
7. Pull Request openen, zodat de wijziging gecontroleerd en overgenomen kan worden.

Stap voor stap met GitHub Desktop¶

1. Repository forken¶

Open het CircusWiki-repository op GitHub:

https://github.com/nica-ev/circuswiki

Klik op Fork. Hierdoor ontstaat een eigen kopie van het repository in je GitHub-account. In deze kopie kun je werken zonder het hoofdproject direct te wijzigen.

2. Repository klonen¶

Open GitHub Desktop en kies:

File -> Clone repository...

Kies je fork van nica-ev/circuswiki en bepaal een map op je computer.

Daarna heb je een lokale kopie van de bestanden.

3. Een branch aanmaken¶

Maak voor je wijziging bij voorkeur een eigen branch aan, bijvoorbeeld:

spel-beschrijving-aanvullen
link-corrigeren
nieuwe-methode-balanceren

Een branch houdt je werk gescheiden van de hoofdversie. Dit maakt de latere controle eenvoudiger.

4. Bestanden bewerken¶

De openbare inhoud staat voornamelijk in de taalmappen onder docs/:

docs/de/
docs/en/
docs/es/
docs/pl/
...
docs/img/

Alle talen zijn gelijkwaardig. Er is geen hoofdtaal waarin nieuwe inhoud in principe moet ontstaan.

Als je een nieuwe originele pagina maakt, plaats deze dan in de taalmap van de taal waarin de tekst is geschreven. Een Spaanse originele tekst hoort bijvoorbeeld in docs/es/, een Duitse in docs/de/, een Engelse in docs/en/.

Belangrijk is de 'frontmatter' aan het begin van het bestand. Daar moet herkenbaar zijn dat de pagina een origineel is, bijvoorbeeld:

translation_status: original
translation_source_lang: es

translation_source_lang komt overeen met de taal van de originele tekst. Vanuit dit origineel kunnen later automatisch vertalingen in alle ondersteunde talen worden gegenereerd.

Let bij het bewerken op het volgende:

• Verwijder de frontmatter aan het begin van het bestand niet.
• Stel bij nieuwe originele pagina's translation_status: original en de juiste translation_source_lang in.
• Behoud bestaande links zoveel mogelijk.
• Publiceer geen privégegevens, API-sleutels of interne notities.
• Gebruik afbeeldingen alleen als de gebruiksrechten duidelijk zijn.
• Maak liever kleine, duidelijke wijzigingen dan zeer grote gemengde wijzigingen.

5. Wijzigingen committen¶

In GitHub Desktop zie je je gewijzigde bestanden in het gedeelte Changes.

Schrijf een korte samenvatting, bijvoorbeeld:

Corrigeer materiaal-lijst in bewegingsspel
Voeg veiligheidsinstructie toe voor Beigoma
Voeg nieuwe spelbeschrijving toe

Klik daarna op Commit to <branch-name>.

6. Wijzigingen uploaden¶

Klik op Push origin om je branch naar GitHub te uploaden.

7. Pull Request openen¶

GitHub Desktop of GitHub in de browser biedt daarna aan om een Pull Request te maken.

Een Pull Request betekent: je stelt je wijziging voor aan het hoofd-repository. De wijziging wordt gecontroleerd, eventueel becommentarieerd en dan overgenomen of verder bewerkt.

Markdown-basis¶

Markdown is een eenvoudig tekstformaat. De belangrijkste tekens zijn voldoende voor de meeste bijdragen:

# Grote kop
## Sectie kop

Normale tekst met **vetgedrukte tekst** en *cursieve tekst*.

- Lijstitem
- Nog een lijstitem

[Linktekst](https://www.example.com)

Als iets onduidelijk is¶

Direct meewerken via GitHub hoef je niet meteen perfect te kunnen. Als je een Pull Request opent en iets nog niet klopt, kan dat in de review worden opgehelderd.

Als je alleen inhoud wilt bijdragen en de technische weg te ingewikkeld lijkt, gebruik dan gewoon de e-mail op de Meedoen-pagina.