diff --git a/source/sv/1.1.0/index.html.haml b/source/sv/1.1.0/index.html.haml new file mode 100644 index 0000000..208f7e6 --- /dev/null +++ b/source/sv/1.1.0/index.html.haml @@ -0,0 +1,308 @@ +--- +description: För en ändringslogg +title: För en ändringslogg +language: sv +version: 1.1.0 +--- +.header + .title + %h1 För en ändringslogg + %h2 Låt inte dina vänner slänga in git-loggar i ändringsloggar. + + = 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" } + Vad är meningen med en ändringslogg? + + %p + För att göra det enklare för användare och medarbetare att se exakt vilka + viktiga ändringar som har gjorts mellan varje utgåva (eller version) av projektet. + + %h3#who + %a.anchor{ href: "#who", aria_hidden: "true" } + Vem behöver en ändringslogg? + + %p + Alla behöver det. Oavsett om det är användare eller utvecklare, är + alla slutanvändare av mjukvaran människor som bryr sig vad som finns + i mjukvaran. När mjukvaran förändras vill folk veta varför och hur. + +.good-practices + %h3#how + %a.anchor{ href: "#how", aria_hidden: "true" } + Hur gör jag en bra ändringslogg? + + %h4#principles + %a.anchor{ href: "#principles", aria_hidden: "true" } + Riktlinjer + + %ul + %li + Ändringsloggar är 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 + Notering att du följer #{link_to "Semantisk versionshantering", data.links.semver}. + + %a.anchor{ href: "#types", aria_hidden: "true" } + %h4#types Typer av ändringar + + %ul + %li + %code Added + för nya funktioner. + %li + %code Changed + för ändringar på existerande funktionalitet. + %li + %code Deprecated + för funktionalitet som snart tas bort. + %li + %code Removed + för nu borttagen funktionalitet. + %li + %code Fixed + för alla buggfixar + %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. Saker så som 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 noterbara + 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 (deprecations) + + %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. Den 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 + Om du inte gör något annat, 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 finns mer. Hjälp mig att samla dessa antimönster genom att + = link_to "skapa ett 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. #{link_to "GNU:s stilguide för ändringsloggar", data.links.gnustyle} och + den #{link_to "två stycke långa GNU NEWS-filen", data.links.gnunews} med "riktlinjer" finns. + 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 tendera 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 följer 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 buggar 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 folk se det. Då den är omsluten med hakparenteser är det också lättare + för ett program att tolka det. + + %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.