mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-29 16:54:12 +02:00
[sl] Add Slovenian - sl_SI translation for 0.3.0
This commit is contained in:
Peter Kokot
parent
41e94beeff
commit
53814393c2
183
source/sl/0.3.0/index.html.haml
Normal file
183
source/sl/0.3.0/index.html.haml
Normal file
@ -0,0 +1,183 @@
|
||||
---
|
||||
description: Keep a Changelog
|
||||
title: Keep a Changelog
|
||||
language: sl
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
:markdown
|
||||
# Vzdržujte dnevnik sprememb oz. CHANGELOG
|
||||
|
||||
## Ne dopustite, da vaši prijatelji odlagajo git dnevnike v CHANGELOG™
|
||||
|
||||
Verzija **#{current_page.metadata[:page][:version]}**
|
||||
|
||||
### Kaj je dnevnik sprememb?
|
||||
Dnevnik sprememb je datoteka, ki vsebuje kuriran, kronološko urejen
|
||||
seznam opaznih sprememb za vsako verzijo projekta.
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
|
||||
:markdown
|
||||
### Kaj je smisel dnevnika sprememb?
|
||||
Za poenostavitev, da uporabniki in prispevajoči sodelavci natančno vidijo, katere
|
||||
opazne spremembe so bile narejene med vsako izdajo (ali verzijo) projekta.
|
||||
|
||||
### Zakaj se truditi?
|
||||
Ker so programska orodja za ljudi. Če vam to ni pomembno, zakaj
|
||||
prispevate odprto kodnemu projektu? Zagotovo mora obstajati malenkost (hehe)
|
||||
skrbnosti nekje v vaši lepi glavi.
|
||||
|
||||
Govorili smo z [Adam-om Stacoviak-om in Jerod-om Santo na temo Changelog-a][thechangelog]
|
||||
(ustrezno, kajne?) podcast o tem zakaj bi se morali vzdrževalci in
|
||||
sodelavci, ki prispevajo, truditi in o motivaciji za tem projektom.
|
||||
Če imate na voljo nekaj časa (1:06), je odlično poslušanje.
|
||||
|
||||
### Kaj naredi dnevnik sprememb odličen?
|
||||
Veseli me, da ste vprašali.
|
||||
|
||||
Dober dnevnik sprememb se drži teh načel:
|
||||
|
||||
- Je enostaven za ljudi, ne stroje, tako da je čitljivost ključnega pomena.
|
||||
- Enostaven za povezavo kateri koli sekciji (torej Markdown pred golim besedilom).
|
||||
- Ena pod-sekcija na verzijo.
|
||||
- Seznam izdaj v obratnem kronološkem vrstnem redu (najnovejše na vrhu).
|
||||
- Zapis vseh datumov v `YYYY-MM-DD` formatu. (Na primer: `2012-06-02` za `2. junij 2012`.) Je mednarnodno, [smiselno](http://xkcd.com/1179/) in neodvisno od jezika.
|
||||
- Eksplicitna omemba ali projekt sledi [semantičnim verzijam][semver].
|
||||
- Vsaka verzija bi morala:
|
||||
- Imeti seznam njenih datumov izdaje v zgornjem formatu.
|
||||
- Skupine sprememb, ki opisujejo njihove vplive na projekt, kot sledi:
|
||||
- `Added` za nove lastnosti.
|
||||
- `Changed` za spremembe obstoječih lastnosti.
|
||||
- `Deprecated` za nekoč stabilne lastnosti, ki bodo odstranjene v prihajajočih verzijah.
|
||||
- `Removed` za zastarele lastnosti, ki so odstranjene v tej izdaji.
|
||||
- `Fixed` za kakršne koli popravke hroščev.
|
||||
- `Security` za povabilo uporabnikom, da nadgradijo v primeru varnostnih ranljivosti.
|
||||
|
||||
### Kako zmanjšati potreben trud?
|
||||
Vedno imejte `"Unreleased"` sekcijo na vrhu za sledenje katerih koli
|
||||
sprememb.
|
||||
|
||||
To služi dvema namenoma:
|
||||
|
||||
- Ljudje lahko vidijo, katere spremembe lahko pričakujejo v prihajajočih izdajah
|
||||
- Pri izdaji, morate tako samo spremembiti `"Unreleased"` v številko verzije
|
||||
in dodati nov naslov `"Unreleased"` na vrh.
|
||||
|
||||
### Kaj spravi samoroga v jok?
|
||||
Dobro … pojdimo skozi.
|
||||
|
||||
- **Odlaganje sprememb git dnevnikov poslanih sprememb.** Temu se izogibajte, saj s tem ne pomagate nikomur.
|
||||
- **Nepoudarjanje zastarelosti.** Ko uporabniki nadgradijo iz ene verzije na
|
||||
drugo, bi moralo biti enostavno jasno, ko nekaj ne bo več delovalo.
|
||||
- **Datumi v lokalnih oblikah.** V ZDA, uporabniki dajo mesec na prvo mesto
|
||||
("06-02-2012" za 2. junij, 2012, kar je brez smisla), medtem ko mnogi ostali
|
||||
uporabniki drugod po svetu pišejo "2 June 2012" robotskega izgleda, vendar
|
||||
izgovorijo to drugače. "2012-06-02" deluje logično po večini in se ne
|
||||
prekriva na dvoumne načine z ostalimi oblikami datumov. To je tudi
|
||||
[ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Tako je to
|
||||
priporočljiva oblika datuma za dnevnike sprememb.
|
||||
|
||||
Tega je še več. Pomagajte zbrati te solze samoroga preko
|
||||
[odprtja težave][issues]
|
||||
ali zahtevka potega.
|
||||
|
||||
### Ali obstaja standardna oblika dnevnika sprememb?
|
||||
Na žalost ne. Vendar mirno kri. Vem, da besno hitite najti to povezavo
|
||||
v vodiču dnevnika sprememb GNU ali v datoteki dveh odstavkov "guideline" GNU
|
||||
NEWS. Stilski vodič GNU je lep začetek, vendar je na žalost preveč enostaven.
|
||||
S tem ni nič narobe, vendar ko uporabniki potrebujejo
|
||||
vodič, je redko v pomoč. Posebej, ko je za reševati veliko
|
||||
situacij in posebnih primerov.
|
||||
|
||||
Ta projekt [vsebuje, kar upamo, da bo postalo boljša datoteka konvencij CHANGELOG][CHANGELOG].
|
||||
Mislimo, da status quo ni dovolj dober in mislimo, da lahko kot skupnost
|
||||
naredimo boljšo konvencijo, če poskusimo izvleči dobre prakse iz
|
||||
realnih programskih projektov. Prosimo, poglejte naokoli in si zapomnite, da
|
||||
[diskusije in predlogi za izboljšave so dobrodošli][issues]!
|
||||
|
||||
### Kako se mora dnevnik sprememb imenovati?
|
||||
Če niste uspeli razbrati iz zgornjega primera, je `CHANGELOG.md`
|
||||
najboljša konvencija do sedaj.
|
||||
|
||||
Nekateri projekti uporabljajo tudi `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
|
||||
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md` itd.
|
||||
|
||||
Gre za zmešnjavo. Vsa ta imena ljudem samo otežijo najti dnevnik sprememb.
|
||||
|
||||
### Zakaj uporabniki ne morejo uporabiti enostavno samo `git log` sprememb?
|
||||
Ker so spremembe dnevnika polne šuma - privzeto. Lahko bi naredili ustrezen
|
||||
dnevnik sprememb tudi v hipotetičnem projektu, ki ga poganjajo popolni ljudje, ki nikoli ne naredijo
|
||||
napak, nikoli ne pozabijo poslati novih datotek in nikoli ne zamudijo nobenega dela refaktorizacije.
|
||||
Razlog pošiljke (commit-a) je dokumentirati en atomičen korak v procesu preko katerega
|
||||
se koda razvija iz enega stanja v drugo. Razlog dnevnika sprememb je
|
||||
dokumentiranje omembe vrednih sprememb med temi stanji.
|
||||
|
||||
Kakor obstaja razlika med dobrimi komentarji in samo kodo,
|
||||
tako je razlika med dnevnikom sprememb in dnevnikom git commit-a:
|
||||
eden opisuje *zakaj*, drugi pa *kako*.
|
||||
|
||||
### Ali se da dnevnik sprememb samodejno razlčeniti?
|
||||
Je težko, ker uporabniki sledijo divje različnim formatom in imenom datotek.
|
||||
|
||||
[Vandamme][vandamme] je Ruby gem,
|
||||
ki ga je ustvarila ekipa [Gemnasium][gemnasium]. Razčlenjuje
|
||||
mnoge (vendar ne vse) dnevnike sprememb odprto kodnih projektov.
|
||||
|
||||
### Zakaj razlikovanje med črkovanjem "CHANGELOG" in "change log"?
|
||||
"CHANGELOG" je ime same datoteke. Je nekoliko glasno, vendar je to
|
||||
zgodovinska konvencija, kateri sledi mnogo odprto kodnih projektov. Drugi
|
||||
primeri podobnih datotek vključujejo [`README`][README], [`LICENSE`][LICENSE],
|
||||
in [`CONTRIBUTING`][CONTRIBUTING].
|
||||
|
||||
Ime z velikimi črkami (kar je datoteko v starih operacijskih sistemih prikazalo na
|
||||
vrhu) je uporabljeno, da se povleče pozornost nanje. Ker gre za pomembne
|
||||
meta podatke o projektu, so lahko uporabne za kogarkoli, ki namerava uporabiti
|
||||
ali prispevati, precej enako kot [značke odprto kodnih projektov][shields].
|
||||
|
||||
Ko se sklicujemo na "change log", govorimo o funkciji te
|
||||
datoteke: beleženje sprememb.
|
||||
|
||||
### Kaj pa povlečene izdaje?
|
||||
T.i. yanked ali povlečene izdaje so verzije, ki so bile primorane biti potegnjene zaradi resnega
|
||||
hrošča ali varnostne težave. Pogostokrat se te verzije niti ne pojavijo v
|
||||
dnevnikih sprememb. Vendar bi se morale. Prikazane bi morale biti sledeče:
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [YANKED]`
|
||||
|
||||
Oznaka `[YANKED]` je izpisana z velikimi črkami z razlogom. Pomembno je, da jo uporabniki
|
||||
opazijo. Ker je obdana z oglatimi oklepaji, jo je tudi enostavnejše razčleniti
|
||||
programsko.
|
||||
|
||||
### Ali bi morali kadarkoli prepisati dnevnik sprememb?
|
||||
Seveda. Vedno obstajajo dobri razlogi, kako izboljšati dnevnik sprememb. Odpiranje
|
||||
zahtevkov potegov je pogostokrat priporočljivo, da se doda manjkajoče izdaje
|
||||
odprtokodnih projektov z nevzdrževanimi dnevniki sprememb.
|
||||
|
||||
Možno je tudi, da odkrijete, da ste pozabili nasloviti pomembne spremembe
|
||||
v opombah verzije. Očitno je pomembno, da vaš
|
||||
dnevnik sprememb v tem primeru posodobite.
|
||||
|
||||
### Kako lahko pomagam?
|
||||
Ta dokument ni **dejstvo**; je osebno temeljito premišljeno
|
||||
mnenje, skupaj z informacijami in primeri, ki smo jih zbrali.
|
||||
Čeprav ponujamo dejanski [CHANGELOG][] v [GitHub repozitoriju][gh],
|
||||
namenoma ni ustvarjene primerne *izdaje* ali jasnega seznama pravil
|
||||
za sledenje (kot ima to npr. [SemVer.org][semver]).
|
||||
|
||||
To je zato, ker želimo, da naša skupnost doseže soglasje. Verjamemo,
|
||||
da je razprava tako pomembna kot končni rezultat.
|
||||
|
||||
Torej, prosimo [**pridružite se**][gh].
|
||||
|
||||
[CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
|
||||
[CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md
|
||||
[LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE
|
||||
[README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md
|
||||
[gemnasium]: https://gemnasium.com/
|
||||
[gh]: https://github.com/olivierlacan/keep-a-changelog
|
||||
[issues]: https://github.com/olivierlacan/keep-a-changelog/issues
|
||||
[semver]: http://semver.org/
|
||||
[shields]: http://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
Loading…
x
Reference in New Issue
Block a user