mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-08-22 18:28:16 +02:00
bee0534514
Previously they had to be duplicated from the page frontmatter but that's not necessary and also makes it possible to have correct OpenGraph title and descriptions.
299 lines
9.3 KiB
Plaintext
299 lines
9.3 KiB
Plaintext
---
|
|
title: Vodite changelog
|
|
description: Ne dajte prijateljima da trpaju git logove u changelogove.
|
|
language: sr
|
|
version: 1.0.0
|
|
---
|
|
.header
|
|
.title
|
|
%h1= current_page.data.title
|
|
%h2= current_page.data.description
|
|
|
|
= link_to data.links.changelog do
|
|
Verzija
|
|
%strong= current_page.metadata[:page][:version]
|
|
|
|
%pre.changelog{ lang: "en" }= File.read("CHANGELOG.md")
|
|
|
|
.answers
|
|
%h3#what
|
|
%a.anchor{ href: "#what", aria_hidden: "true" }
|
|
Šta je changelog?
|
|
|
|
%p
|
|
Changelog je datoteka koja sadrži uređeni hronološki
|
|
poređani popis značajnih promena unutar svake verzije projekta.
|
|
|
|
%h3#why
|
|
%a.anchor{ href: "#why", aria_hidden: "true" }
|
|
Zašto voditi changelog?
|
|
|
|
%p
|
|
Kako bi korisnici i saradnici detaljno videli
|
|
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 menja, 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 mašinama.
|
|
%li
|
|
Potrebno je stvoriti unos za svaku verziju.
|
|
%li
|
|
Slične promene potrebno je grupisati.
|
|
%li
|
|
Verzije i odeljci trebaju imati vezu.
|
|
%li
|
|
Poslednja verzija treba biti na prvom mestu.
|
|
%li
|
|
Datum izdavanja svake pojedine verzije treba biti vidljiv.
|
|
%li
|
|
Navesti prati li se #{link_to "Semantičko verzioniranje", data.links.semver}.
|
|
|
|
%a.anchor{ href: "#types", aria_hidden: "true" }
|
|
%h4#types Vrste promena
|
|
|
|
%ul
|
|
%li
|
|
%code Added
|
|
za nove funkcionalnosti.
|
|
%li
|
|
%code Changed
|
|
za promene u postojećim funkcionalnostima.
|
|
%li
|
|
%code Deprecated
|
|
za funkcionalnosti koje će se ukloniti u budućim verzijama.
|
|
%li
|
|
%code Removed
|
|
za uklonjene funkcionalnosti.
|
|
%li
|
|
%code Fixed
|
|
za ispravke bagova.
|
|
%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 gde ćete navoditi nadolazeće
|
|
promene.
|
|
|
|
%p To radimo iz dva razloga:
|
|
|
|
%ul
|
|
%li
|
|
Korisnici mogu videti promene 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,
|
|
promene u dokumentaciji i sl.
|
|
|
|
%p
|
|
Svrha commita je da beleži korake u razvoju izvornog koda.
|
|
U nekim projektima se comittovi čiste, no ponekad i ne.
|
|
|
|
%p
|
|
Svrha unosa u changelogu je da belež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" }
|
|
Ignorisanje uklonjenih funkcionalnosti
|
|
|
|
%p
|
|
Kad korisnici nadograde softver na noviju verziju, treba biti potpuno
|
|
jasno da postoji mogućnost da će se neki deo 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
|
|
gde su već uklonjene.
|
|
|
|
%p
|
|
U najmanju ruku, potrebno je u changelogu navoditi funkcionalnosti koje će
|
|
biti uklonjene, funkcionalnosti koje su uklonjene i promene koje će
|
|
uticati na rad softvera (breaking change).
|
|
|
|
|
|
%h4#confusing-dates
|
|
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
|
Nejasni datumi
|
|
|
|
%p
|
|
Regionalni formati datuma variraju delom sveta, 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 poređan
|
|
od veće prema manjoj jedinici: godina, mesec, dan. Ovaj je format takođe
|
|
teško zameniti s drugim regionalnim formatima, za razliku od nekih koji,
|
|
primera radi, menjaju poziciju oznake meseca i dana.
|
|
Iz tog razloga, a i zbog toga što je navedeni format #{link_to "ISO standard", data.links.isodate},
|
|
taj se format preporučuje za changelog unose.
|
|
|
|
%aside
|
|
Ali to nije sve. Pomozite u prikupljanju primera loše prakse
|
|
= link_to "otvorivši issue", data.links.issue
|
|
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", data.links.gnustyle},
|
|
i #{link_to "GNU NEWS file", data.links.gnunews}
|
|
"priručnik od dva odlomka". Nijedan nije adekvatan ni dovoljan.
|
|
|
|
%p
|
|
Cilj ovoga projekta
|
|
= link_to "kvalitetniji changelog standard.", data.links.changelog
|
|
Nastao je prikupljanjem primera dobra prakse u
|
|
open source zajednici.
|
|
|
|
%p
|
|
Konstruktivna kritika, raprave i predlozi za poboljšanje
|
|
= link_to "su dobrodošli.", data.links.issue
|
|
|
|
|
|
%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 delovati 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" }
|
|
Šta s GitHub Releases?
|
|
|
|
%p
|
|
To je ozbiljna inicijativa. #{link_to "Releases", data.links.github_releases} se mogu koristiti
|
|
kako bi git oznake (npr. git oznaka <code>v1.0.0</code>) pretvorili
|
|
u opširnije beleš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 repozitorijuma. 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 interfejs ne nudi poveznice na commit logove
|
|
između izdanja.
|
|
|
|
%h4#automatic
|
|
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
|
Mogu li changelogovi automatski parsirati?
|
|
|
|
%p
|
|
Teže, jer se koriste vrlo različiti formati, kao i nazivi datoteka.
|
|
|
|
%p
|
|
#{link_to "Vandamme", data.links.vandamme} je Ruby gem koji je kreirao
|
|
Gemnasium tim i može parsirati mnoge (ali
|
|
ne sve) changelogove projekata otvorenog koda.
|
|
|
|
|
|
%h4#yanked
|
|
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
|
Šta s povučenim izdanjima?
|
|
|
|
%p
|
|
Povučena ili 'Yanked' izdanja su verzije koje su uklonjene zbog
|
|
ozbiljnijeg baga ili sigurnosnog propusta. Takva se izdanja najčešće
|
|
i ne pojavljuju u changelogu, iako bi trebala. Trebala bi biti navedena
|
|
na sledeć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 primetiti. Buduće da je okružena zagradama, takođe ju
|
|
je lakše parsirati.
|
|
|
|
|
|
%h4#rewrite
|
|
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
|
Da li je 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 changelogove.
|
|
|
|
%p
|
|
Moguće je, takođe da otkrijete, kako ste zaboravili navesti promenu koja
|
|
bi uticala na rad (breaking change). U tom slučaju je, očito, vrlo bitno
|
|
ažurirati changelog.
|
|
|
|
|
|
%h4#contribute
|
|
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
|
Kako doprineti?
|
|
|
|
%p
|
|
Ovaj dokument nije <em>Sveto Pismo</em>; ovo je samo pažljivo
|
|
razmotreno mišljenje, uz informacije i primere koje sam skupio.
|
|
|
|
%p
|
|
Razlog je tome to što želim da zajednica postigne konsenzus. Verujem,
|
|
takođe, da je i sama rasprava bitna kao i krajnji rezultat.
|
|
|
|
%p
|
|
Zato, molimo <strong>#{link_to "uskočite", data.links.repo}</strong>.
|
|
|
|
.press
|
|
%h3 Razgovori
|
|
%p
|
|
Gostovao sam na #{link_to "The Changelog podcastu", data.links.thechangelog}
|
|
gde sam pokušao objasniti zašto začetnici projekata i saradnici trebaju
|
|
brinuti o changelogovima te motivaciji iza ovog projekta.
|