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>.",
|
||||
new: "Une nouvelle version est disponible"
|
||||
},
|
||||
"hr" => {
|
||||
name: "Hrvatski"
|
||||
},
|
||||
"id-ID" => {
|
||||
name: "Indonesia",
|
||||
new: "Ada versi baru tersedia"
|
||||
|
||||
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