mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-29 08:44:16 +02:00
Add Serbian translations
This commit is contained in:
Zoranzoki21
parent
4f0ffb69cd
commit
d9564f9675
311
source/sr/1.0.0/index.html.haml
Normal file
311
source/sr/1.0.0/index.html.haml
Normal file
@ -0,0 +1,311 @@
|
||||
---
|
||||
description: Vodite changelog
|
||||
title: Vodite changelog
|
||||
language: hr
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
|
||||
- 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" }
|
||||
Š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", 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", iso},
|
||||
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", 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 ovoga projekta
|
||||
= link_to "kvalitetniji changelog standard.", 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.", 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 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", ghr} 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", 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", gh}</strong>.
|
||||
|
||||
.press
|
||||
%h3 Razgovori
|
||||
%p
|
||||
Gostovao sam na #{link_to "The Changelog podcastu", thechangelog}
|
||||
gde sam pokušao objasniti zašto začetnici projekata i saradnici trebaju
|
||||
brinuti o changelogovima te motivaciji iza ovog projekta.
|
||||
Loading…
x
Reference in New Issue
Block a user