mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-28 16:24:07 +02:00
Olivier Lacan
GitHub
commit
a875b55fdc
@ -39,6 +39,9 @@ $languages = {
|
|||||||
l'instant et <a href='#{issues_url}'>aider à la traduire</a>.",
|
l'instant et <a href='#{issues_url}'>aider à la traduire</a>.",
|
||||||
new: "Une nouvelle version est disponible"
|
new: "Une nouvelle version est disponible"
|
||||||
},
|
},
|
||||||
|
"hr" => {
|
||||||
|
name: "Hrvatski"
|
||||||
|
},
|
||||||
"id-ID" => {
|
"id-ID" => {
|
||||||
name: "Indonesia",
|
name: "Indonesia",
|
||||||
new: "Ada versi baru tersedia"
|
new: "Ada versi baru tersedia"
|
||||||
@ -92,7 +95,7 @@ $languages = {
|
|||||||
},
|
},
|
||||||
"ko" => {
|
"ko" => {
|
||||||
name: "한국어"
|
name: "한국어"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
activate :i18n,
|
activate :i18n,
|
||||||
|
|||||||
312
source/hr/1.0.0/index.html.haml
Normal file
312
source/hr/1.0.0/index.html.haml
Normal file
@ -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 <em> ljudima</em>, 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 <code>Unreleased</code> 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 <code>Unreleased</code> 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 <code>2017-07-17</code> 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 <code>CHANGELOG.md</code>. Neki projekti još koriste
|
||||||
|
<code>HISTORY</code>, <code>NEWS</code> ili <code>RELEASES</code>.
|
||||||
|
|
||||||
|
%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 <code>v1.0.0</code>) 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
|
||||||
|
(<code>README</code>, <code>CONTRIBUTING</code>, 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 <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
|
||||||
|
|
||||||
|
%p
|
||||||
|
<code>[YANKED]</code> 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 <em>Sveto Pismo</em>; 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 <strong>#{link_to "uskočite", gh}</strong>.
|
||||||
|
|
||||||
|
.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.
|
||||||
Loading…
x
Reference in New Issue
Block a user