diff --git a/.gitignore b/.gitignore index 865ecdb..ef48534 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ /.sass-cache /build /_site +/.vs diff --git a/source/sv/1.0.0/index.html.haml b/source/sv/1.0.0/index.html.haml new file mode 100644 index 0000000..875992e --- /dev/null +++ b/source/sv/1.0.0/index.html.haml @@ -0,0 +1,300 @@ +--- +description: Håll en ändringslogg +title: Håll en ändringslogg +language: sv +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 Håll en ändringslogg + %h2 Låt inte dina vänner slänga in git-loggar i ändringsloggar. + + = link_to changelog do + Version + %strong= current_page.metadata[:page][:version] + + %pre.changelog= 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 "Semantic Versioning", 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 + I USA lägger folk månaden först (06-02-2012 för 2:a juni 2012), + medan många andra runt om i världen skriver 2 June 2012 men + uttalar det annorlunda. 2012-06-02 fungerar logiskt från störst + till minst, överlappar inte på något tvetydligt sätt med andra datumformat, + och är en #{link_to "ISO-standard", iso}. Dessutom är det rekommenderat + datumformat för ändringsloggar. + + %aside + Det finns mer. Hjälp mig att samla dessa antimönster + genom att = link_to "skapa ett issue", "#issues" 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. GNU:s stilguide för ändringsloggar och den två stycke + långa GNU NEWS-filen 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.", 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.", issues + + %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", ghr} 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å + Håll 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", vandamme} är en Ruby gem skapad av gruppen + #{link_to "Gemnasium", 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 brådskande utgåvor ("yanked")? + + %p + Brådskande utgåvor är versioner som måste släppas på grund av alvarliga + 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, gh}. + +.press + %h3 Samtal + %p + Jag var med i #{link_to "The Changelog podcast", thechangelog} + för att prata om varför förvaltare och bidragsgivare bör bry sig om + ändringsloggar, och motiveringen bakom detta projekt.