Vzdržujte dnevnik sprememb oz. CHANGELOG

Ne dopustite, da vaši prijatelji odlagajo git dnevnike v CHANGELOG™

Verzija 0.3.0

Kaj je dnevnik sprememb?

Dnevnik sprememb je datoteka, ki vsebuje kuriran, kronološko urejen seznam opaznih sprememb za vsako verzijo projekta.

# Change Log
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/) 
and this project adheres to [Semantic Versioning](http://semver.org/).

## [Unreleased]
### Added
- zh-CN and zh-TW translations from @tianshuo.
- de translation from @mpbzh.
- it-IT translation from @roalz.
- sv translation from @magol.
- tr-TR translation from @karalamalar.
- fr translation from @zapashcanon.

### Changed
- Start versioning based on the current English version at 0.3.0 to help
translation authors keep things up-to-date.
- Fix typos in zh-CN translation.
- Fix typos in pt-BR translation.

## [0.3.0] - 2015-12-03
### Added
- RU translation from @aishek.
- pt-BR translation from @tallesl.
- es-ES translation from @ZeliosAriex.

## [0.2.0] - 2015-10-06
### Changed
- Remove exclusionary mentions of "open source" since this project can benefit
both "open" and "closed" source projects equally.

## [0.1.0] - 2015-10-06
### Added
- Answer "Should you ever rewrite a change log?".

### Changed
- Improve argument against commit logs.
- Start following [SemVer](http://semver.org) properly.

## [0.0.8] - 2015-02-17
### Changed
- Update year to match in every README example.
- Reluctantly stop making fun of Brits only, since most of the world
  writes dates in a strange way.

### Fixed
- Fix typos in recent README changes.
- Update outdated unreleased diff link.

## [0.0.7] - 2015-02-16
### Added
- Link, and make it obvious that date format is ISO 8601.

### Changed
- Clarified the section on "Is there a standard change log format?".

### Fixed
- Fix Markdown links to tag comparison URL with footnote-style links.

## [0.0.6] - 2014-12-12
### Added
- README section on "yanked" releases.

## [0.0.5] - 2014-08-09
### Added
- Markdown links to version tags on release headings.
- Unreleased section to gather unreleased changes and encourage note
keeping prior to releases.

## [0.0.4] - 2014-08-09
### Added
- Better explanation of the difference between the file ("CHANGELOG")
and its function "the change log".

### Changed
- Refer to a "change log" instead of a "CHANGELOG" throughout the site
to differentiate between the file and the purpose of the file — the
logging of changes.

### Removed
- Remove empty sections from CHANGELOG, they occupy too much space and
create too much noise in the file. People will have to assume that the
missing sections were intentionally left out because they contained no
notable changes.

## [0.0.3] - 2014-08-09
### Added
- "Why should I care?" section mentioning The Changelog podcast.

## [0.0.2] - 2014-07-10
### Added
- Explanation of the recommended reverse chronological release ordering.

## 0.0.1 - 2014-05-31
### Added
- This CHANGELOG file to hopefully serve as an evolving example of a standardized open source project CHANGELOG.
- CNAME file to enable GitHub Pages custom domain
- README now contains answers to common questions about CHANGELOGs
- Good examples and basic guidelines, including proper date formatting.
- Counter-examples: "What makes unicorns cry?"

[Unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...HEAD
[0.3.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.8...v0.1.0
[0.0.8]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.7...v0.0.8
[0.0.7]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.6...v0.0.7
[0.0.6]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.5...v0.0.6
[0.0.5]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.4...v0.0.5
[0.0.4]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.3...v0.0.4
[0.0.3]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.2...v0.0.3
[0.0.2]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.1...v0.0.2

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 (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:

Kako zmanjšati potreben trud?

Vedno imejte "Unreleased" sekcijo na vrhu za sledenje katerih koli sprememb.

To služi dvema namenoma:

Kaj spravi samoroga v jok?

Dobro … pojdimo skozi.

Tega je še več. Pomagajte zbrati te solze samoroga preko odprtja težave 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. 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!

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 je Ruby gem, ki ga je ustvarila ekipa 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, LICENSE, in 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.

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, namenoma ni ustvarjene primerne izdaje ali jasnega seznama pravil za sledenje (kot ima to npr. SemVer.org).

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.