mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-08-23 02:38:14 +02:00
bee0534514
Previously they had to be duplicated from the page frontmatter but that's not necessary and also makes it possible to have correct OpenGraph title and descriptions.
320 lines
10 KiB
Plaintext
320 lines
10 KiB
Plaintext
---
|
|
title: Hold en changelog
|
|
description: Du skal ikke lade dine venner smide git logs i changelogs.
|
|
language: da
|
|
version: 1.1.0
|
|
---
|
|
.header
|
|
.title
|
|
%h1= current_page.data.title
|
|
%h2= current_page.data.description
|
|
|
|
= link_to data.links.changelog do
|
|
Version
|
|
%strong= current_page.metadata[:page][:version]
|
|
|
|
%pre.changelog{ lang: "en" }= File.read("CHANGELOG.md")
|
|
|
|
.answers
|
|
%h3#what
|
|
%a.anchor{ href: "#what", aria_hidden: "true" }
|
|
Hvad er en changelog?
|
|
|
|
%p
|
|
En changelog er en fil, der indeholder en organiseret, kronologisk
|
|
sorteret liste af bemærkelsesværdige ændringer for hver version
|
|
af et projekt.
|
|
|
|
%h3#why
|
|
%a.anchor{ href: "#why", aria_hidden: "true" }
|
|
Hvorfor have en changelog?
|
|
|
|
%p
|
|
For at gøre det nemmere for brugere og bidragsydere at se præcist
|
|
hvilke bemærkelsesværdige ændringer, der er lavet mellem hver
|
|
udgivelse eller version af et projekt.
|
|
|
|
%h3#who
|
|
%a.anchor{ href: "#who", aria_hidden: "true" }
|
|
Hvem skal bruge en changelog?
|
|
|
|
%p
|
|
Det skal folk. Om det er forbrugere eller udviklere, er slutbrugere
|
|
mennesker, der bekymrer sig om, hvad der er i et stykke software. Når
|
|
softwaren ændrer sig, vil folk gerne vide hvad, og hvordan.
|
|
|
|
.good-practices
|
|
%h3#how
|
|
%a.anchor{ href: "#how", aria_hidden: "true" }
|
|
Hvordan laver jeg en god changelog?
|
|
|
|
%h4#principles
|
|
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
|
Retningslinjer
|
|
|
|
%ul
|
|
%li
|
|
Changelogs er til <em>for mennesker</em>, ikke maskiner.
|
|
%li
|
|
Der skal være et indlæg for hver eneste version.
|
|
%li
|
|
Ens typer af ændringer skal grupperes.
|
|
%li
|
|
Versioner og sektioner skal være link-bare.
|
|
%li
|
|
Den seneste version står først.
|
|
%li
|
|
Udgivelsesdatoen for hver version vises.
|
|
%li
|
|
Nævn hvorvidt du følger #{link_to "Semantisk Versionering", data.links.semver}.
|
|
|
|
%a.anchor{ href: "#types", aria_hidden: "true" }
|
|
%h4#types Ændringstyper
|
|
|
|
%ul
|
|
%li
|
|
%code Tilføjet (Added)
|
|
til nye funktioner.
|
|
%li
|
|
%code Ændret (Dhanged)
|
|
til rettelser i eksisterende funktionalitet.
|
|
%li
|
|
%code Udfaset (Deprecated)
|
|
til funktioner, der fjernes snart.
|
|
%li
|
|
%code Fjernet (Removed)
|
|
til fjernede funktioner.
|
|
%li
|
|
%code Rettet (Fixed)
|
|
til fejlrettelser.
|
|
%li
|
|
%code Sikkerhed (Security)
|
|
i tilfælde af sårbarheder.
|
|
|
|
.effort
|
|
|
|
%h3#effort
|
|
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
|
Hvordan kan jeg reducere indsatsen ved at opretholde en changelog?
|
|
|
|
%p
|
|
Hav en <code>Unreleased</code> sektion i toppen til kommende
|
|
rettelser.
|
|
|
|
%p Dette tjener to formål:
|
|
|
|
%ul
|
|
%li
|
|
Folk kan se, hvilke rettelser de kan forvente i den kommende
|
|
udgivelse
|
|
%li
|
|
Ved udgivelsen kan du flytte <code>Unreleased</code> sektionens
|
|
rettelser ind i en ny versionssektion.
|
|
|
|
.bad-practices
|
|
%h3#bad-practices
|
|
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
|
Kan changelogs være dårlige?
|
|
|
|
%p Ja. Her er et par måder, de kan være mindre brugbare.
|
|
|
|
%h4#log-diffs
|
|
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
|
Commit log diffs
|
|
|
|
%p
|
|
At bruge commit log differenser som changelog er en dårlig idé:
|
|
De er fyldt med støj. Ting som merge-commits, commits med obskure titler,
|
|
dokumentationsrettelser osv.
|
|
|
|
%p
|
|
Formålet med et commit er at dokumentere et trin i udviklingen af
|
|
kildekoden. Nogle projekter rydder op i deres commits, andre gør
|
|
ikke.
|
|
|
|
%p
|
|
Formålet med en changelog-indlæg er at dokumentere de bemærkelsesværdige
|
|
forskelle, ofte fordelt over flere commits, for at formidle dem klart
|
|
til slutbrugerene.
|
|
|
|
%h4#ignoring-deprecations
|
|
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
|
At ignorere udfasninger
|
|
|
|
%p
|
|
Når folk opgraderer fra én version til en anden, skal det være helt
|
|
tydeligt, hvorvidt noget vil gå i stykker. Det skal være muligt
|
|
at opgradere til en version, der opsummerer udfasninger, fjerner
|
|
gamle udfasniner, og opgradere til dén version, hvor udfasningerne
|
|
bliver til oprydninger.
|
|
|
|
%p
|
|
Hvis du ikke gør andet, så notér udfasninger, fjernede funktioner
|
|
og andre ødelæggende ændringer.
|
|
|
|
|
|
%h4#confusing-dates
|
|
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
|
Forvirrende datoer
|
|
|
|
%p
|
|
Regionale dataformater er varierende i hele verden, og det er ofte
|
|
besværligt at finde et læsbart datoformat, der føles intuitivt for alle
|
|
Fordelen ved datoer formatteret som <code>2017-07-17</code> er at de
|
|
følger rækkefølgen for største til mindste enhed: år, måned og dag.
|
|
Dette format overlapper heller ikke på en tvetydig måde med andre
|
|
datoformater, der ombytter måneden og daten. Af disse årsager, og
|
|
det faktum at dette datoformat er en #{link_to "ISO standard", data.links.isodate},
|
|
er dette det anbefalede datoformat for changelog-indlæg.
|
|
|
|
%h4#inconsistent-changes
|
|
%a.anchor{ href: "#inconsistent-changes", aria_hidden: "true" }
|
|
Ukonsistente rettelser
|
|
|
|
%p
|
|
En changelog, der kun nævner nogle af ændringerne, kan være lige så
|
|
farlig som ikke at have en changelog. Mens mange af ændringerne
|
|
måske ikke er relevante - for eksempel er det ikke være nødvendigt at
|
|
notere, at vi har fjernet et enkelt mellemrum - bør væsentlige
|
|
ændringer være nævnt i changeloggen. Ved inkonsekvent at anvende
|
|
ændringer, kan dine brugere fejlagtigt tro, at changelog er den
|
|
eneste kilde til sandhed. Det bør den være. Med store
|
|
magtbeføjelser følger store forpligtigelser. At have en god changelog
|
|
er at have en konsekvent opdateret changelog.
|
|
|
|
%aside
|
|
Der er mere. Hjælp mig med at samle disse fælder ved at
|
|
= link_to "åbne et issue", data.links.issue
|
|
eller et pull-request.
|
|
|
|
.frequently-asked-questions
|
|
%h3#frequently-asked-questions
|
|
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
|
Ofte stillede spørgsmål
|
|
|
|
%h4#standard
|
|
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
|
Er der et standard changelog-format?
|
|
|
|
%p
|
|
Ikke rigtig. Der er #{link_to "GNU changelog style guide", data.links.gnustyle},
|
|
eller #{link_to "two-paragraph-long GNU NEWS file", data.links.gnunews}. De
|
|
er begge utilstrækkelige eller uhensigtsmæssige.
|
|
|
|
%p
|
|
Dette projekt sigter efter at være
|
|
= link_to "en bedre changelog konvention.", data.links.changelog
|
|
Det kommer af at observere god praksis i opensource-verdenen
|
|
og samle disse.
|
|
|
|
%p
|
|
Konstruktiv kritik diskussion og forbedringsforslag
|
|
= link_to "er velkomne.", data.links.issue
|
|
|
|
|
|
%h4#filename
|
|
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
|
Hvad skal changelog-filen hedde?
|
|
|
|
%p
|
|
Kald den <code>CHANGELOG.md</code>. Nogle projekter bruger
|
|
<code>HISTORY</code>, <code>NEWS</code> eller <code>RELEASES</code>.
|
|
|
|
%p
|
|
Selvom det er nemt at mene, at navnet på changelog-filen er
|
|
irrelevant, hvorfor så gøre det sværere for dine slugbrugere
|
|
at finde bemærkelsesværdige ændringer?
|
|
|
|
|
|
%h4#github-releases
|
|
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
|
Hvad med GitHub Releases?
|
|
|
|
%p
|
|
Det er et godt initiativ. #{link_to "Releases", data.links.github_releases} kan bruges
|
|
til at gøre simple git tags (for eksempel, et tag <code>v1.0.0</code>)
|
|
til fyldige udgivelsesnoter ved manuelt at tilføje noter til disse
|
|
eller bruge en annoteret git-tag-besked som udgivelsesnoter.
|
|
|
|
%p
|
|
GitHub Releases laver en ikke-flytbar changelog, der kun kan vises
|
|
til bruger i konteksten af GitHub. Det er muligt at få dem til at
|
|
ligne Hold en changelog-formatet, men det har en tendens til at
|
|
være lidt mere kompliceret.
|
|
|
|
%p
|
|
Den nuværende version af GitHub releases er, diskutérbart,
|
|
ikke særligt synlig for slutbrugere, ikke lig de typiske
|
|
kapitaliserede filer (<code>README</code>,
|
|
<code>CONTRIBUTING</code>, osv.). Et andet mindre problem, er
|
|
at interfacet ikke tilbyder links til commit logs mellem hvert
|
|
release.
|
|
|
|
%h4#automatic
|
|
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
|
Kan changelogs læses og fortolkes automatisk?
|
|
|
|
%p
|
|
Det er besværligt, fordi folk følger vidt forskellige formater
|
|
og filnavne.
|
|
|
|
%p
|
|
#{link_to "Vandamme", data.links.vandamme} er en Ruby gem lavet af
|
|
holdet bag Gemnasium, som læser og fortolker mange (men ikke
|
|
alle) open source projekters changelogs.
|
|
|
|
%h4#yanked
|
|
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
|
Hvad med tilbagetrukkede udgivelser?
|
|
|
|
%p
|
|
Tilbagetrukkede udgivelser er versioner, der er blevet trukket
|
|
tilbage på grund af en seriøs fejl eller sikkerhedsbrist. Ofte
|
|
vises disse versioner slet ikke i changelogs. Det bør de. Dette
|
|
er hvordan du bør vise dem:
|
|
|
|
%p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
|
|
|
|
%p
|
|
Notationen <code>[YANKED]</code>, er højlydt af en årsag: Det er
|
|
vigtig information for folk. Siden den er pakket ind i klammer, er
|
|
den nemmere at fortolke og læse systematiseret.
|
|
|
|
|
|
%h4#rewrite
|
|
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
|
Bør man nogensinde omskrive en changelog?
|
|
|
|
%p
|
|
Klart! Der er altid gode grunde til at forbedre en changelog.
|
|
Jeg åbner jævnligt pull-requests, der tilføjer manglende releases
|
|
til open source projekter uden en vedligeholdt changelog.
|
|
|
|
%p
|
|
Det er også muligt, at du vil opdage at du har glemt at addressere
|
|
en ødelæggende rettelse i noterne for en version. Det er selvfølgelig
|
|
vigtigt at du opdaterer en changelog i disse tilfælde.
|
|
|
|
|
|
%h4#contribute
|
|
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
|
Hvordan kan jeg hjælpe til?
|
|
|
|
%p
|
|
Dette dokument er ikke <strong>sandheden</strong>; det er min
|
|
velovervejede mening sammen med information og eksempler jeg har
|
|
samlet.
|
|
|
|
%p
|
|
Det er fordi, jeg gerne vil have at vores fællesskab når en konsensus.
|
|
Jeg mener at diskussionen er lige så vigtig som slutresultatet.
|
|
%p
|
|
Så, <strong>#{link_to "vær med!", data.links.repo}</strong>
|
|
|
|
.press
|
|
%h3 Samtaler
|
|
%p
|
|
Jeg var med i #{link_to "The Changelog podcast", data.links.thechangelog} for
|
|
at snakke om, hvorfor vedligeholdere og bidragsydere bør bekymre sig
|
|
om changelogs og også om motivationen bag dette projekt.
|