--- title: För en ändringslogg description: Låt inte vänner dumpa git-loggar i ändringsloggar. language: sv 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" } Vad är en ändringslogg? %p En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad lista över viktiga ändringar för varje version av ett projekt. %h3#why %a.anchor{ href: "#why", aria_hidden: "true" } Varför föra en ändringslogg? %p För att göra det enklare för användare och medarbetare att se exakt vilka viktiga ändringar som har skett mellan varje utgåva (eller version) av projektet. %h3#who %a.anchor{ href: "#who", aria_hidden: "true" } Vem behöver en ändringslogg? %p Folk i allmänhet. Oavsett om de är användare eller utvecklare, är alla slutanvändare av mjukvaran människor som bryr sig om vad som finns i den. När mjukvaran förändras vill de veta varför och hur. .good-practices %h3#how %a.anchor{ href: "#how", aria_hidden: "true" } Hur skapar jag en bra ändringslogg? %h4#principles %a.anchor{ href: "#principles", aria_hidden: "true" } Riktlinjer %ul %li Ändringsloggar är till för människor, inte maskiner. %li Det bör finnas en post för varje enskild version. %li Samma typ av ändringar bör grupperas. %li Det bör vara möjligt att länka till versioner och sektioner. %li Senaste versionen kommer först. %li Datum då respektive version släpptes ska visas. %li Nämn huruvida du använder #{link_to "Semantisk versionshantering", data.links.semver}. %a.anchor{ href: "#types", aria_hidden: "true" } %h4#types Ändringstyper %ul %li %code Added för nya funktioner. %li %code Changed för ändringar i existerande funktionalitet. %li %code Deprecated för funktionalitet som snart tas bort. %li %code Removed för borttagen funktionalitet. %li %code Fixed för felrättningar %li %code Security i fall av sårbarheter. .effort %h3#effort %a.anchor{ href: "#effort", aria_hidden: "true" } Hur kan jag minimera den insats som krävs för att underhålla en ändringslogg? %p Ha en sektion kallad Unreleased högst upp för att hålla reda på kommande ändringar. %p Detta tjänar två syften: %ul %li Folk kan se vilka ändringar de kan förvänta sig i kommande utgåvor %li Vid lansering behöver du bara flytta innehållet i sektionen Unreleased till en ny versionspost. .bad-practices %h3#bad-practices %a.anchor{ href: "#bad-practices", aria_hidden: "true" } Kan ändringsloggar vara dåliga? %p Ja, här är några exempel på då de är mindre användbara. %h4#log-diffs %a.anchor{ href: "#log-diffs", aria_hidden: "true" } Diffar från incheckningsloggen. %p Det är en dålig idé att använda incheckningsloggen som ändringslogg: de är fulla av brus; merge-incheckningar, incheckningar med otydliga titlar, dokumentationsförändringar etc. %p Syftet med en incheckning är att dokumentera ett steg i utvecklingen av källkoden. Vissa projekt städar upp bland incheckningarna, andra inte. %p Syftet med en post i en ändringslogg är att dokumentera den märkbara skillnaden, oftast över flera incheckningar, för att kommunicera dessa tydligt till slutanvändaren. %h4#ignoring-deprecations %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } Ignorera föråldrad funktionalitet %p När användare uppgraderar från en version till en annan, ska det vara smärtsamt uppenbart när något förväntas gå sönder. Det bör vara möjligt att uppgradera till en version som listar föråldrad funktionalitet, ta bort dessa beroenden i sitt program, och sedan uppgradera till en version där den föråldrade funktionaliteten är borttagen. %p Även om du inte gör något annat, så lista åtminstone föråldrad och borttagen funktionalitet samt förstörande förändringar i din ändringslogg. %h4#confusing-dates %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } Förvillande datum %p Lokala datumformat varierar över hela världen, och det är ofta svårt att hitta ett användbart datumformat som känns intuitivt för alla. Fördelen med datumformat så som 2017-07-17 är att det följer storleksordningen från störst till minst: år, månad och dag. Detta format överlappar inte heller på ett tvetydligt sätt med andra datumformat, till skillnad från lokala format som kan växla positionen på månad och dag. Dessa anledningar tillsammans med det faktum att detta datumformat är en #{link_to "ISO-standard", data.links.isodate}, gör att detta är rekommenderat format för ändringsloggar. %h4#inconsistent-changes %a.anchor{ href: "#inconsistent-changes", aria_hidden: "true" } Inkonsekventa ändringar %p En ändringslogg som endast nämner vissa av ändringarna kan vara lika riskabel som att inte ha någon ändringslogg alls. Även om många av ändringarna kanske inte är relevanta - till exempel behöver kanske inte borttagningen av ett enskilt blanksteg alltid nämnas - bör alla viktiga ändringar nämnas i ändringsloggen. Genom att inkonsekvent lägga in ändringar kan dina användare felaktigt tro att ändringsloggen är den enda källan till sanning. Så borde det vara. Med stor makt följer stort ansvar - att ha en bra ändringslogg innebär att ha en konsekvent uppdaterad ändringslogg. %aside Det var inte allt. Hjälp mig att samla dessa antimönster genom att = link_to "skapa en issue", data.links.issue eller en pull requests .frequently-asked-questions %h3#frequently-asked-questions %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" } Vanliga frågor %h4#standard %a.anchor{ href: "#standard", aria_hidden: "true" } Finns det ett standardformat på ändringsloggar? %p Inte riktigt. Det finns #{link_to "GNU:s stilguide för ändringsloggar", data.links.gnustyle} och den #{link_to "två stycken-långa GNU NEWS-filen", data.links.gnunews} med "riktlinjer". Båda är bristfälliga och otillräckliga. %p Detta projekt har som mål att bli = link_to "en bättre konvention för ändringsloggar.", data.links.changelog Det utgår från uppenbart goda praxis från öppen källkods-världen och sammanför dem. %p Konstruktiv kritik, diskussion och förslag till förbättring = link_to "är välkommen.", data.links.issue %h4#filename %a.anchor{ href: "#filename", aria_hidden: "true" } Vad bör filen med ändringsloggen heta? %p Döp den till CHANGELOG.md. En del projekt använder HISTORY, NEWS eller RELEASES. %p Även om det är lätt att tänka att det inte spelar så stor roll vad filen med ändringsloggar kallas, varför göra det svårare för dina slutanvändare att enkelt hitta de viktigaste ändringarna? %h4#github-releases %a.anchor{ href: "#github-releases", aria_hidden: "true" } Hur är det med GitHub Releases? %p Det är ett fantasiskt initiativ. #{link_to "Releases", data.links.github_releases} kan användas för att göra enkla git-taggar (t.ex. en tagg kallad v1.0.0) till formaterade versionsanteckningar genom att manuellt lägga till versionsanteckningar eller så kan den hämta meddelandena i kommenterade git-taggar och omvandla dessa till versionsanteckningar. %p GitHub Releases skapar en icke porterbar ändringslogg som enbart kan visas för användare på GitHub. Det är möjligt att formatera det ungefär som på För en ändringslogg-formatet, men det tenderar att bli lite mer invecklat. %p Nuvarande version av GitHub releases är möjligtvis också lite svår att hitta för slutanvändare, till skillnad från filer med normalt stora bokstäver (README, CONTRIBUTING, etc.). Ett annat bekymmer är att användargränssnittet för närvarande inte erbjuder länkar till incheckningsloggar mellan olika versioner. %h4#automatic %a.anchor{ href: "#automatic", aria_hidden: "true" } Kan ändringsloggar bli automatiskt tolkade? %p Det är svårt då människor använder vitt olika format och filnamn. %p #{link_to "Vandamme", data.links.vandamme} är en Ruby gem skapad av gruppen Gemnasium som tolkar många (men inte alla) ändringsloggar för öppen källkod. %h4#yanked %a.anchor{ href: "#yanked", aria_hidden: "true" } Hur är det med återtagna utgåvor ("yanked")? %p Återtagna utgåvor är versioner som måste tas tillbaka på grund av allvarliga programfel eller säkerhetsproblem. Oftast brukar dessa versioner inte ens finnas med i ändringsloggarna. De borde det. Så här borde du visa dem: %p ## [0.0.5] - 2014-12-13 [YANKED] %p Taggen [YANKED] står ut av en anledning; det är viktigt att den syns. Då den är omsluten med hakparenteser är det också lättare för ett program att tolka den. %h4#rewrite %a.anchor{ href: "#rewrite", aria_hidden: "true" } Borde du någonsin förändra en ändringslogg? %p Självklart. Det finns alltid en bra anledning att förbättra en ändringslogg. Jag öppnar regelbundet pull requests för att lägga till saknade utgåvor för öppna källkodsprojekt som inte tar hand om sin ändringslogg. %p Det kan också hända att du upptäcker att du glömt att ta upp en icke bakåtkompatibel förändring i en version. I sådana fall är det självklart viktigt att uppdatera din ändringslogg. %h4#contribute %a.anchor{ href: "#contribute", aria_hidden: "true" } Hur kan jag bidra? %p Detta dokument är inte sanningen, det är en noga övervägd åsikt tillsammans med information och exempel jag har samlat på mig. %p Detta beror på att jag vill att vår gemenskap ska nå enighet. Jag tror på att diskussionen är lika viktig som slutresultatet. %p Så tveka inte att #{link_to "kasta dig in i diskussionen", data.links.repo}. .press %h3 Samtal %p Jag var med i #{link_to "The Changelog podcast", data.links.thechangelog} för att prata om varför förvaltare och bidragsgivare bör bry sig om ändringsloggar, och motiveringen bakom detta projekt.