Keep a Changelog

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

Version 0.3.0

Kaj je dnevnik sprememb?

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

# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- v1.1 Brazilian Portuguese translation.
- v1.1 German Translation
- v1.1 Spanish translation.
- v1.1 Italian translation.
- v1.1 Polish translation.
- v1.1 Ukrainian translation.

### Changed

- Use frontmatter title & description in each language version template
- Replace broken OpenGraph image with an appropriately-sized Keep a Changelog 
  image that will render properly (although in English for all languages)
- Fix OpenGraph title & description for all languages so the title and 
description when links are shared are language-appropriate

### Removed

- Trademark sign previously shown after the project description in version 
0.3.0

## [1.1.1] - 2023-03-05

### Added

- Arabic translation (#444).
- v1.1 French translation.
- v1.1 Dutch translation (#371).
- v1.1 Russian translation (#410).
- v1.1 Japanese translation (#363).
- v1.1 Norwegian Bokmål translation (#383).
- v1.1 "Inconsistent Changes" Turkish translation (#347).
- Default to most recent versions available for each languages.
- Display count of available translations (26 to date!).
- Centralize all links into `/data/links.json` so they can be updated easily.

### Fixed

- Improve French translation (#377).
- Improve id-ID translation (#416).
- Improve Persian translation (#457).
- Improve Russian translation (#408).
- Improve Swedish title (#419).
- Improve zh-CN translation (#359).
- Improve French translation (#357).
- Improve zh-TW translation (#360, #355).
- Improve Spanish (es-ES) transltion (#362).
- Foldout menu in Dutch translation (#371).
- Missing periods at the end of each change (#451).
- Fix missing logo in 1.1 pages.
- Display notice when translation isn't for most recent version.
- Various broken links, page versions, and indentations.

### Changed

- Upgrade dependencies: Ruby 3.2.1, Middleman, etc.

### Removed

- Unused normalize.css file.
- Identical links assigned in each translation file.
- Duplicate index file for the english version.

## [1.1.0] - 2019-02-15

### Added

- Danish translation (#297).
- Georgian translation from (#337).
- Changelog inconsistency section in Bad Practices.

### Fixed

- Italian translation (#332).
- Indonesian translation (#336).

## [1.0.0] - 2017-06-20

### Added

- New visual identity by [@tylerfortune8](https://github.com/tylerfortune8).
- Version navigation.
- Links to latest released version in previous versions.
- "Why keep a changelog?" section.
- "Who needs a changelog?" section.
- "How do I make a changelog?" section.
- "Frequently Asked Questions" section.
- New "Guiding Principles" sub-section to "How do I make a changelog?".
- Simplified and Traditional Chinese translations from [@tianshuo](https://github.com/tianshuo).
- German translation from [@mpbzh](https://github.com/mpbzh) & [@Art4](https://github.com/Art4).
- Italian translation from [@azkidenz](https://github.com/azkidenz).
- Swedish translation from [@magol](https://github.com/magol).
- Turkish translation from [@emreerkan](https://github.com/emreerkan).
- French translation from [@zapashcanon](https://github.com/zapashcanon).
- Brazilian Portuguese translation from [@Webysther](https://github.com/Webysther).
- Polish translation from [@amielucha](https://github.com/amielucha) & [@m-aciek](https://github.com/m-aciek).
- Russian translation from [@aishek](https://github.com/aishek).
- Czech translation from [@h4vry](https://github.com/h4vry).
- Slovak translation from [@jkostolansky](https://github.com/jkostolansky).
- Korean translation from [@pierceh89](https://github.com/pierceh89).
- Croatian translation from [@porx](https://github.com/porx).
- Persian translation from [@Hameds](https://github.com/Hameds).
- Ukrainian translation from [@osadchyi-s](https://github.com/osadchyi-s).

### Changed

- Start using "changelog" over "change log" since it's the common usage.
- Start versioning based on the current English version at 0.3.0 to help
  translation authors keep things up-to-date.
- Rewrite "What makes unicorns cry?" section.
- Rewrite "Ignoring Deprecations" sub-section to clarify the ideal
  scenario.
- Improve "Commit log diffs" sub-section to further argument against
  them.
- Merge "Why can’t people just use a git log diff?" with "Commit log
  diffs".
- Fix typos in Simplified Chinese and Traditional Chinese translations.
- Fix typos in Brazilian Portuguese translation.
- Fix typos in Turkish translation.
- Fix typos in Czech translation.
- Fix typos in Swedish translation.
- Improve phrasing in French translation.
- Fix phrasing and spelling in German translation.

### Removed

- Section about "changelog" vs "CHANGELOG".

## [0.3.0] - 2015-12-03

### Added

- RU translation from [@aishek](https://github.com/aishek).
- pt-BR translation from [@tallesl](https://github.com/tallesl).
- es-ES translation from [@ZeliosAriex](https://github.com/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](https://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/v1.1.1...HEAD
[1.1.1]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.0...v1.1.1
[1.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0
[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
[0.0.1]: https://github.com/olivierlacan/keep-a-changelog/releases/tag/v0.0.1

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.