diff --git a/config.rb b/config.rb index de6daf1..0a1d288 100644 --- a/config.rb +++ b/config.rb @@ -39,6 +39,9 @@ $languages = { l'instant et aider à la traduire.", new: "Une nouvelle version est disponible" }, + "hr" => { + name: "Hrvatski" + }, "id-ID" => { name: "Indonesia", new: "Ada versi baru tersedia" @@ -92,7 +95,7 @@ $languages = { }, "ko" => { name: "한국어" - } + } } activate :i18n, diff --git a/source/hr/1.0.0/index.html.haml b/source/hr/1.0.0/index.html.haml new file mode 100644 index 0000000..3e8eebb --- /dev/null +++ b/source/hr/1.0.0/index.html.haml @@ -0,0 +1,312 @@ +--- +description: Vodite changelog +title: Vodite changelog +language: hr +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 = "https://semver.org/" +- shields = "https://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/" +- gnustyle = "https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs" +- gnunews = "https://www.gnu.org/prep/standards/html_node/NEWS-File.html#NEWS-File" + +.header + .title + %h1 Vodite Changelog + %h2 Ne dajte prijateljima da trpaju git logove u changelogove. + + = link_to changelog do + Verzija + %strong= current_page.metadata[:page][:version] + + %pre.changelog= File.read("CHANGELOG.md") + +.answers + %h3#what + %a.anchor{ href: "#what", aria_hidden: "true" } + Što je changelog? + + %p + Changelog je datoteka koja sadrži uređeni kronološki + poredani popis značajnih promjena unutar svake verzije projekta. + + %h3#why + %a.anchor{ href: "#why", aria_hidden: "true" } + Zašto voditi changelog? + + %p + Kako bi korisnici i suradnici detaljno vidjeli + značajne promjene među pojedinim izdanjima (ili verzijama) + projekta. + + %h3#who + %a.anchor{ href: "#who", aria_hidden: "true" } + Kome treba changelog? + + %p + Ljudima. Bilo da su uobičajeni korisnici ili programeri, krajnji su korisnici + softvera ljudska bića kojima je stalo do toga od čega je sastavljen. Kada + se softver mijenja, korisnici žele znati kako i zašto. + +.good-practices + %h3#how + %a.anchor{ href: "#how", aria_hidden: "true" } + Kako kreirati dobar changelog? + + %h4#principles + %a.anchor{ href: "#principles", aria_hidden: "true" } + Glavna načela + + %ul + %li + Changelogs služi ljudima, ne strojevima. + %li + Potrebno je stvoriti unos za svaku verziju. + %li + Slične promjene potrebno je grupirati. + %li + Verzije i sekcije trebaju imati poveznicu. + %li + Posljednja verzija treba biti na prvom mjestu. + %li + Datum izdavanja svake pojedine verzije treba biti vidljiv. + %li + Navesti prati li se #{link_to "Semantičko verzioniranje", semver}. + + %a.anchor{ href: "#types", aria_hidden: "true" } + %h4#types Vrste promjena + + %ul + %li + %code Added + za nove funkcionalnosti. + %li + %code Changed + za promjene u postojećim funkcionalnostima. + %li + %code Deprecated + za funcionalnosti koje će se ukloniti u budućim verzijama. + %li + %code Removed + za uklonjene funkcionalnosti. + %li + %code Fixed + za ispravke bugova. + %li + %code Security + za slučaj sigurnosnih propusta. + +.effort + + %h3#effort + %a.anchor{ href: "#effort", aria_hidden: "true" } + Kako održavati changelog sa što manje napora? + + %p + Na vrh postavite Unreleased sekciju gdje ćete navoditi nadolazeće + promjene. + + %p To radimo iz dva razloga: + + %ul + %li + Korisnici mogu vidjeti promjene koje mogu očekivati u nadolazećim izdanjima + %li + Kod izdavanja nove verzije, moguće je Unreleased sekciju + samo preimenovati u novo izdanje. + +.bad-practices + %h3#bad-practices + %a.anchor{ href: "#bad-practices", aria_hidden: "true" } + Može li changelog biti loš? + + %p Naravno. Postoji nekoliko slučajeva u kojima changelog može biti beskoristan. + + %h4#log-diffs + %a.anchor{ href: "#log-diffs", aria_hidden: "true" } + Commit log diffovi + + %p + Korištenje commit log diffova u svrhu changeloga nije dobra ideja: + puni su šuma. Npr. merge commitovi, commitovi s nejasnim naslovima, + promjene u dokumentaciji i sl. + + %p + Svrha commita je da bilježi korake u razvoju izvornog koda. + U nekim projektima se comittovi čiste, no ponekad i ne. + + %p + Svrha unosa u changelogu je da bilježi značajne razlike, a + često kroz više commitova i jasno ih prenese krajnjem + korisniku. + + %h4#ignoring-deprecations + %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } + Ignoriranje uklonjenih funcionalnosti + + %p + Kad korisnici nadograde softver na noviju verziju, treba biti potpuno + jasno da postoji mogućnost da će se neki dio pokvariti. Softver treba biti + moguće nadograditi na verziju koja će navesti funkcionalnosti koje trebaju + biti uklonjene, uklanja takve te se kasnije može nadograditi na verziju + gdje su već uklonjene. + + %p + U najmanju ruku, potrebno je u changelogu navoditi funkcionalnosti koje će + biti uklonjene, funkcionalnosti koje su uklonjene i promjene koje će + utjecati na rad softvera (breaking change). + + + %h4#confusing-dates + %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } + Nejasni datumi + + %p + Regionalni formati datuma variraju diljem svijeta, pa je često + teško pronaći format datuma koji će odgovarati svima. + Prednost datuma u formatu 2017-07-17 je to što je poredan + od veće prema manjoj jedinici: godina, mjesec, dan. Ovaj je format također + teško zamijeniti s drugim regionalnim formatima, za razliku od nekih koji, + primjerice mijenjaju poziciju oznake mjeseca i dana. + Iz tog razloga, a i zbog toga što je navedeni format #{link_to "ISO standard", iso}, + taj se format preporuča za changelog unose. + + %aside + Ali to nije sve. Pomozite prikupiti primjere loše prakse + = link_to "otvorivši issue", issues + ili pull request. + +.frequently-asked-questions + %h3#frequently-asked-questions + %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" } + Česta pitanja + + %h4#standard + %a.anchor{ href: "#standard", aria_hidden: "true" } + Postoji li standardni changelog format? + + %p + Zapravo ne. Postoji #{link_to "GNU changelog stilski priručnik", gnustyle}, + i #{link_to "GNU NEWS file", gnunews} + "priručnik od dva odlomka". Nijedan nije adekvatan ni dovoljan. + + %p + Cilj je ovoga projekta + = link_to "kvalitetniji changelog standard.", changelog + Nastao je prikupljanjem primjera dobra prakse u + open source zajednici. + + %p + Konstruktivna kritika, raprave i prijedlozi za poboljšanje + = link_to "su dobrodošli.", issues + + + %h4#filename + %a.anchor{ href: "#filename", aria_hidden: "true" } + Kako nazvati changelog datoteku? + + %p + Dajemo joj naziv CHANGELOG.md. Neki projekti još koriste + HISTORY, NEWS ili RELEASES. + + %p + Iako može djelovati da naziv changelog datoteke i nije toliko + bitan, čemu otežavati korisnicima da dođu do informacije o promjenama? + + %h4#github-releases + %a.anchor{ href: "#github-releases", aria_hidden: "true" } + Što s GitHub Releases? + + %p + To je ozbilja inicijativa. #{link_to "Releases", ghr} se mogu koristiti + kako bi git oznake (npr. git oznaka v1.0.0) pretvorili + u opširnije bilješke o izdanju, upisujući ih ručno ili pak preuzimajući + anotirane git oznake i pretvarajući ih u unose. + + %p + GitHub Releases stvara statični changelog vidljiv korisnicima + unutar GitHub repozitorija. Moguće ih je urediti u format koji + bi odgovarao Vodite changelog formatu, no često je nešto opširniji. + + %p + Trenutna GitHub releases verzija i nije baš sasvim vidljiva + korisnicima, za razliku od uobičajenih datoteka označenih velikim slovima + (README, CONTRIBUTING, itd.). Još je jedan + manji problem što trenutno sučelje ne nudi poveznice na commit logove + između izdanja. + + %h4#automatic + %a.anchor{ href: "#automatic", aria_hidden: "true" } + Mogu li changelogovi automatski parsati? + + %p + Teže, jer se koriste vrlo različiti formati, kao i nazivi datoteka. + + %p + #{link_to "Vandamme", vandamme} je Ruby gem koji je kreirao + #{link_to "Gemnasium", gemnasium} tim i može parsati mnoge (ali + ne sve) changeloge projekata otvorenog koda. + + + %h4#yanked + %a.anchor{ href: "#yanked", aria_hidden: "true" } + Što s povučenim izanjima? + + %p + Povučena ili 'Yanked' izdanja su verzije koje su uklonjene zbog + ozbiljnijeg buga ili sigurnosnog propusta. Takva se izdanja najčešće + i ne pojavljuju u changelogu, iako bi trebala. Trebala bi biti navedena + na sljedeći način: + + %p ## 0.0.5 - 2014-12-13 [YANKED] + + %p + [YANKED] oznaka jasno je istaknuta s razlogom. Bitno je + da ju je lako primijetiti. Buduće da je okružena zagradama, također ju + je lakše parsati. + + + %h4#rewrite + %a.anchor{ href: "#rewrite", aria_hidden: "true" } + Je li potrebno prepravljati changelog? + + %p + Naravno. Često postoje dobri razlozi da bismo poboljšali changelog. Ja + često otvaram pull requestove kako bih dodao nedostajuća izdanja projektima + otvorenog koda, koji ne održavaju changeloge. + + %p + Moguće je, također da otkrijete, kako ste zaboravili navesti promjenu koja + bi utjecala na rad (breaking change). U tom je slučaju, očito, vrlo bitno + ažurirati changelog. + + + %h4#contribute + %a.anchor{ href: "#contribute", aria_hidden: "true" } + Kako doprinijeti? + + %p + Ovaj dokument nije Sveto Pismo; ovo je samo pažljivo + razmotreno mišljenje, uz informacije i primjere koje sam skupio. + + %p + Razlog je tome to što želim da zajednica postigne konsenzus. Vjerujem, + također, da je i sama rasprava bitna kao i krajnjni rezultat. + + %p + Zato, molimo #{link_to "uskočite", gh}. + +.press + %h3 Razgovori + %p + Gostovao sam na #{link_to "The Changelog podcastu", thechangelog} + gdje sam pokušao objasniti zašto začetnici projekata i suradnici trebaju + brinuti o changelogovima te motivaciji iza ovog projekta.