mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-30 17:24:25 +02:00
Merge pull request #211 from jkrielaars/master
Dutch translation of 1.0.0
This commit is contained in:
Olivier Lacan
GitHub
commit
8109a6b763
299
source/nl/1.0.0/index.html.haml
Normal file
299
source/nl/1.0.0/index.html.haml
Normal file
@ -0,0 +1,299 @@
|
||||
---
|
||||
description: Keep a Changelog
|
||||
title: Keep a Changelog
|
||||
language: nl
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
|
||||
- gemnasium = "https://gemnasium.com/"
|
||||
- gh = "https://github.com/olivierlacan/keep-a-changelog"
|
||||
- issues = "https://github.com/olivierlacan/keep-a-changelog/issues"
|
||||
- semver = "http://semver.org/"
|
||||
- shields = "http://shields.io/"
|
||||
- thechangelog = "http://5by5.tv/changelog/127"
|
||||
- vandamme = "https://github.com/tech-angels/vandamme/"
|
||||
- iso = "http://www.iso.org/iso/home/standards/iso8601.htm"
|
||||
- ghr = "https://help.github.com/articles/creating-releases/"
|
||||
|
||||
.header
|
||||
.title
|
||||
%h1 Houd een Changelog bij
|
||||
%h2 Laat je vrienden geen git logs in changelogs dumpen.
|
||||
|
||||
= link_to changelog do
|
||||
Versie
|
||||
%strong= current_page.metadata[:page][:version]
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
|
||||
.answers
|
||||
%h3#what
|
||||
%a.anchor{ href: "#what", aria_hidden: "true" }
|
||||
Wat is een changelog?
|
||||
|
||||
%p
|
||||
Een changelog is een bestand met een zorgvuldig samengestelde, chronologische lijst
|
||||
van noemenswaardige aanpassingen voor elke versie van een project.
|
||||
|
||||
%h3#why
|
||||
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||||
Waarom een changelog bijhouden?
|
||||
|
||||
%p
|
||||
Om het makkelijker te maken voor gebruikers en programmeurs om precies te zien welke
|
||||
noemenswaardige aanpassingen er gedaan zijn tussen elke release (of versie) van het project.
|
||||
|
||||
%h3#who
|
||||
%a.anchor{ href: "#who", aria_hidden: "true" }
|
||||
Wie heeft een changelog nodig?
|
||||
|
||||
%p
|
||||
Mensen hebben het nodig. Of het nu consumenten of ontwikkelaars zijn, eindgebruikers van
|
||||
software zijn mensen die er om geven wat er in de software zit die ze gebruiken.
|
||||
Als de software veranderd, wil men weten wat en hoe.
|
||||
|
||||
.good-practices
|
||||
%h3#how
|
||||
%a.anchor{ href: "#how", aria_hidden: "true" }
|
||||
Hoe maak ik een goed changelog?
|
||||
|
||||
%h4#principles
|
||||
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
||||
Richtlijnen
|
||||
|
||||
%ul
|
||||
%li
|
||||
Changelogs zijn <em>voor mensen</em>, niet voor machines.
|
||||
%li
|
||||
Er zou een vermelding moeten zijn voor elke versie.
|
||||
There should be an entry for every single version.
|
||||
%li
|
||||
Aanpassingen van het zelfde type moeten gegroepeerd worden.
|
||||
%li
|
||||
Versies en secties zouden linkbaar moeten zijn.
|
||||
%li
|
||||
De laatste versie staat bovenaan.
|
||||
%li
|
||||
De release datum van elke versie word weergegeven.
|
||||
%li
|
||||
Geef aan of je #{link_to "Semantic Versioning", semver} gebruikt.
|
||||
|
||||
%a.anchor{ href: "#types", aria_hidden: "true" }
|
||||
%h4#types Types of changes
|
||||
|
||||
%ul
|
||||
%li
|
||||
%code Added
|
||||
voor nieuwe functionaliteit.
|
||||
%li
|
||||
%code Changed
|
||||
voor aanpassingen aan bestaande functionaliteit.
|
||||
%li
|
||||
%code Deprecated
|
||||
voor functionaliteit die binnenkort komt te vervallen.
|
||||
%li
|
||||
%code Removed
|
||||
voor functionaliteit die vanaf nu vervallen is.
|
||||
%li
|
||||
%code Fixed
|
||||
voor bug fixes.
|
||||
%li
|
||||
%code Security
|
||||
voor aanpassingen met betrekking tot veiligheid.
|
||||
|
||||
.effort
|
||||
|
||||
%h3#effort
|
||||
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
||||
Hoe kan ik, met zo min mogelijk moeite, een changelog bij houden?
|
||||
|
||||
%p
|
||||
Houd bovenin een <code>Unreleased</code> sectie bij met aanpassingen voor de komende release.
|
||||
|
||||
%p Dit heeft twee doelen:
|
||||
|
||||
%ul
|
||||
%li
|
||||
Mensen kunnen zien wat te verwachten in de aankomende release.
|
||||
%li
|
||||
Als je een release doet kan je eenvoudig de <code>Unreleased</code> sectie
|
||||
aanpassen naar een nieuwe release sectie.
|
||||
|
||||
.bad-practices
|
||||
%h3#bad-practices
|
||||
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||||
Kan een changelog slecht zijn?
|
||||
|
||||
%p Ja. Hier een paar manieren waarop je een changelog behoorlijk onbruikbaar kan maken.
|
||||
|
||||
%h4#log-diffs
|
||||
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||||
Commit log diffs
|
||||
|
||||
%p
|
||||
Commit log diffs gebruiken als een changelog is een slecht idee:
|
||||
ze staan vol met ruis. Denk bijvoorbeeld aan merge commits, commits met
|
||||
onduidelijke titels, documentatie aanpassingen etc.
|
||||
|
||||
%p
|
||||
Het doel van een commit bericht is om één enkele stap in de evolutie van de
|
||||
code te beschrijven.
|
||||
|
||||
%p
|
||||
Het doel van een changelog is om noemenswaardige aanpassingen te documenteren,
|
||||
vaak over meerdere commits, en om deze duidelijk naar de eindgebruiker te communiceren.
|
||||
|
||||
%h4#ignoring-deprecations
|
||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||
Deprecations negeren
|
||||
|
||||
%p
|
||||
Wanneer mensen upgraden van de ene naar de andere versie,
|
||||
moet het overduidelijk zijn als er iets niet meer zal werken.
|
||||
Het moet mogelijk zijn om te upgraden naar een versie met deprications,
|
||||
vervolgens de deprications weg te halen, en vervolgens
|
||||
de upgrade kunnen doen naar de versie waar de deprications removals zijn geworden.
|
||||
|
||||
%p
|
||||
Geef altijd op zijn minst de deprications, removals en changes met grote impact aan in je changelog.
|
||||
|
||||
%h4#confusing-dates
|
||||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||
Verwarrende datums
|
||||
|
||||
%p
|
||||
Datum notaties verschillen van land tot land, en het is vaak moeilijk om
|
||||
een notatie te vinden die makkelijk te lezen is en intuitief is voor iedereen.
|
||||
|
||||
Het voordeel van de notatie <code>2017-07-17</code> is dat het jaar, maand en dag
|
||||
op volgorde van grootte laat zien. Daarom, en het feit dat dit een #{link_to "ISO standaard", iso}
|
||||
is, is dit de aanbevolen datum notatie voor changelog releases.
|
||||
|
||||
%aside
|
||||
Dit is niet alles. Help mij antipatterns te verzamelen door
|
||||
= link_to "een issue", issues
|
||||
of een pull request aan te maken.
|
||||
|
||||
.frequently-asked-questions
|
||||
%h3#frequently-asked-questions
|
||||
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
||||
Veel Gestelde Vragen
|
||||
|
||||
%h4#standard
|
||||
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
||||
Is er een standaard changelog template?
|
||||
|
||||
%p
|
||||
Niet echt. Er is de GNU changelog style guide, en het twee paragrafen lange GNU NEWS bestand "richtlijnen".
|
||||
Beiden zijn niet volledig genoeg.
|
||||
|
||||
%p
|
||||
Dit project poogt
|
||||
= link_to "een betere changelog standaard", changelog
|
||||
te creëren. Dit op basis van "good practices" uit de open source wereld.
|
||||
|
||||
%p
|
||||
Opbouwende kritiek, discussie en suggesties voor verbetering
|
||||
= link_to "zijn welkom.", issues
|
||||
|
||||
|
||||
%h4#filename
|
||||
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
||||
Wat zou de changelog bestandsnaam moeten zijn?
|
||||
|
||||
%p
|
||||
Noem het <code>CHANGELOG.md</code>. Sommige projecten gebruiken
|
||||
<code>HISTORY</code>, <code>NEWS</code> of <code>RELEASES</code>.
|
||||
|
||||
%p
|
||||
Je kan denken dat de bestandsnaam niet heel belangrijk is,
|
||||
maar waarom zou je het de eindgebruikers moeilijker maken om de changelog te vinden?
|
||||
|
||||
%h4#github-releases
|
||||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||||
Wat denk je van GitHub Releases?
|
||||
|
||||
%p
|
||||
Het is een goed initiatief. #{link_to "Releases", ghr} kan gebruikt worden
|
||||
om simpele git tags (bijvoorbeeld een tag met de naam <code>v1.0.0</code>)
|
||||
te veranderen in uitgebreide release notes door deze handmatig toe te voegen of
|
||||
door geannoteerde git tag berichten te gebruiken om release notes te genereren.
|
||||
|
||||
%p
|
||||
GitHub Releases maken changelog wat alleen getoond kan worden aan gebruikers
|
||||
binnen de context van GitHub. Het is mogelijk om deze dicht bij het format
|
||||
te krijgen wat wij hier promoten, maar er zal iets meer werk voor nodig zijn.
|
||||
|
||||
%p
|
||||
De huidige versie van GitHub releases is naar mijn mening niet
|
||||
echt goed vindbaar voor gebruikers, in tegenstelling tot de typische
|
||||
bestanden die in een naam in hoofdletters hebben
|
||||
(<code>README</code>, <code>CONTRIBUTING</code>, etc.).
|
||||
Een ander knelpunt is dat de interface geen links toestaat naar
|
||||
commit logs van elke release.
|
||||
|
||||
%h4#automatic
|
||||
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
||||
Kunnen changelogs automatisch geparsed worden?
|
||||
|
||||
%p
|
||||
Dat is lasig, mensen gebruiken immers veel verschillende formats en bestandsnamen.
|
||||
|
||||
%p
|
||||
#{link_to "Vandamme", vandamme} is een Ruby gem van het
|
||||
#{link_to "Gemnasium", gemnasium} team wat de changelogs van veel (maar niet alle)
|
||||
open source projecten kan parsen.
|
||||
|
||||
|
||||
%h4#yanked
|
||||
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
||||
Wat doen we met teruggetrokken (yanked) releases?
|
||||
|
||||
%p
|
||||
Teruggetrokken releases zijn versies die teruggetrokken zijn als gevolg
|
||||
van een serieuze bug of beveiligings probleem. Vaak zijn ze niet eens te zien in
|
||||
de changelogs. Dat zou wel moeten. Zo zou je een teruggetrokken release moeten tonen:
|
||||
|
||||
%p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
|
||||
|
||||
%p
|
||||
De <code>[YANKED]</code> tag is in hoofdletters voor een reden. Het is belangrijk
|
||||
dat mensen dit zien. Omdat het tussen blokhaken genoteerd is, is het ook makkelijker
|
||||
automatisch te parsen.
|
||||
|
||||
|
||||
%h4#rewrite
|
||||
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
||||
Mag je een changelog aanpassen/herschrijven?
|
||||
|
||||
%p
|
||||
Natuurlijk. Er zijn goede redenen om een changelog te verbeteren.
|
||||
Ik open regelmatig een pull request om missende releases toe te
|
||||
voegen aan open source projecten met een slecht onderhouden changelog.
|
||||
|
||||
%p
|
||||
Het kan ook zo zijn dat je ontdekt dat je een belangrijke aanpassing niet
|
||||
vermeld hebt in je changelog. Het is dan natuurlijk zaak om dit alsnog
|
||||
in je changelog te vermelden.
|
||||
|
||||
%h4#contribute
|
||||
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
||||
Hoe kan ik bijdragen?
|
||||
|
||||
%p
|
||||
Dit document is niet de <strong>waarheid</strong>; het is mijn
|
||||
weloverwogen mening, samen met wat informatie en voorbeelden die ik verzameld heb.
|
||||
|
||||
%p
|
||||
Dit heb ik gedaan omdat ik wil dat de programmeer gemeenschap een consensus bereikt.
|
||||
Ik denk dat de discussie net zo belangrijk is als het eindresultaat.
|
||||
|
||||
%p
|
||||
Dus <strong>#{link_to "alle hulp is welkom", gh}</strong>.
|
||||
|
||||
.press
|
||||
%h3 Conversaties
|
||||
%p
|
||||
Ik was te gast bij #{link_to "The Changelog podcast", thechangelog} om te praten over
|
||||
waarom een changelog belangrijk is programmeurs, en over mijn motivatie achter dit project.
|
||||
Loading…
x
Reference in New Issue
Block a user