Udržuj changelog

Nenechaj kamarátov sypať git logy do changelogov.

Verzia 1.0.0
# 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.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
### Changed
- Update and improvement of Polish translation from [@m-aciek](https://github.com/m-aciek).

## [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 [@karalamalar](https://github.com/karalamalar).
- French translation from [@zapashcanon](https://github.com/zapashcanon).
- Brazilian Portugese translation from [@Webysther](https://github.com/Webysther).
- Polish translation from [@amielucha](https://github.com/amielucha).
- 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).

### 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.0.0...HEAD
[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

Čo je to changelog?

Changelog je súbor obsahujúci organizovaný, chronologicky usporiadaný zoznam významných zmien pre každú verziu daného projektu.

Prečo udržiavať changelog?

Aby používatelia a prispievatelia presne vedeli, aké podstatné zmeny sa udiali medzi jednotlivými vydaniami (alebo verziami) projektu.

Kto potrebuje changelog?

Ľudia. Či už konzumenti, alebo vývojári, koncoví používatelia softvéru sú ľudské bytosti, ktorým záleží na tom, čo softvér obsahuje. Keď sa softvér zmení, ľudia chcú vedieť prečo a ako.

Ako vytvorím dobrý changelog?

Hlavné princípy

  • Changelogy sú pre ľudí, nie stroje.
  • Changelog by mal obsahovať záznam pre každú jednu verziu.
  • Rovnaké typy zmien by mali byť zoskupené.
  • Mala by existovať možnosť odkazovať na jednotlivé verzie a sekcie.
  • Posledná verzia je uvedená na prvom mieste.
  • Pre každú verziu je uvedený dátum jej vydania.
  • Uveď tiež, že sa držíš sémantického verziovania.

Typy zmien

  • Added pre nové funkcie.
  • Changed pre zmeny existujúcej funkcie.
  • Deprecated pre funkcie, ktoré budú čoskoro odstránené.
  • Removed pre odstránené funkcie.
  • Fixed pre opravy chýb.
  • Security v prípade bezpečnostných zraniteľností.

Ako minimalizovať úsilie vynaložené na udržiavanie changelogu?

Udržuj Unreleased sekciu na začiatku changelogu pre nadchádzajúce zmeny.

Má to dva dôvody:

  • Ľudia môžu vidieť, aké zmeny môžu očakávať v ďalších vydaniach
  • V čase vydávania novej verzie môžeš presunúť zmeny z Unreleased sekcie do sekcie novej verzie

Môžu byť changelogy zlé?

Áno. Tu je hneď niekoľko spôsobov, ako môžu byť neužitočné.

Diffy z commit logu

Použitie diffov z commit logu ako changelog nie je dobrý nápad: sú plné balastu. Veci ako merge commity, commity s nejasnými názvami, zmeny dokumentácie a pod.

Účel commitu je dokumentovanie kroku v evolúcii zdrojového kódu. Niektoré projekty commity prečisťujú, iné nie.

Účelom changelogu je dokumentovanie významných zmien, často naprieč viacerými commitmi, a jasne ich komunikovať koncovému používateľovi.

Ignorovanie oznámenia zastaralých funkcií

Keď používatelia prechádzajú na novšiu verziu, musí byť jasné, čo sa rozbije. Mala by pre nich existovať možnosť prejsť na verziu so zoznamom zastaralých funkcií, tieto funkcie odstrániť a následne prejsť na verziu, kde sú tieto zastaralé funkcie už odstránené.

Ak už nič iné, tak aspoň uveď zastaralé, odstránené funkcie a všetky zmeny, ktoré môžu niečo rozbiť, do changelogu.

Mätúce dátumy

Regionálne formáty dátumov sa líšia naprieč svetom a často je zložité nájsť formát dátumu, ktorý by bol prívetivý a intuitívny pre všetkých používateľov. Výhodou dátumu vo formáte 2017-07-17 je poradie od najväčšej jednotky po najmenšiu: rok, mesiac, deň. Tento formát sa tiež neprekrýva s inými formátmi, ktoré zamieňajú pozíciu dňa a mesiaca. Kvôli týmto dôvodom spolu s faktom, že ide o ISO štandard, je tento formát odporučený pre záznamy v changelogu.

Často kladené otázky

Existuje štandardný formát pre changelog?

Nie. Existuje GNU príručka pre štýl changelogu alebo dvojodstavcová GNU "smernica" pre NEWS súbor. Obe sú však nevhodné či nedostatočné.

Tento projekt sa snaží byť lepšou konvenciou pre changelog. Vychádza z pozorovania a zozbierania osvedčených postupov komunity okolo projektov s otvoreným zdrojovým kódom.

Zdravá kritika, diskusia a návrhy na zlepšenie sú vítané.

Ako by mal byť súbor changelogu pomenovaný?

Nazvi ho CHANGELOG.md. Niektoré projekty používajú tiež HISTORY, NEWS alebo RELEASES.

Je jednoduché myslieť si, že názov changelogu nie je taký dôležitý. Prečo však sťažovať koncovému používateľovi hľadanie významných zmien?

A čo GitHub Releases?

Je to skvelá iniciatíva. Služba Releases môže byť použitá pre premenu git tagov (napríklad tagu v1.0.0) na bohaté poznámky k vydaniam manuálnym pridávaním týchto poznámok alebo získaním správ z anotovaných git tagov a vytvorením poznámok k vydaniu z nich.

GitHub Releases vytvorí neprenosný changelog, ktorý môže byť zobrazený používateľom v rámci GitHubu. Je možné ich upraviť na veľmi podobný štýl, aký navrhuje projekt Udržuj changelog, tento postup však býva trochu zložitejší.

Súčasná verzia GitHub Releases tiež nie je ľahko objaviteľná koncovým používateľom, na rozdiel od klasického súboru s názvom napísaným veľkými písmenami (README, CONTRIBUTING atď.). Ďalším menším problémom je, že v súčasnosti nepodporuje odkazy na commit logy medzi jednotlivými vydaniami.

Môžu byť changelogy automaticky parsované?

Je to zložité, pretože ľudia používajú rôzne formáty a názvy súborov.

Vandamme je Ruby gem vytvorený tímom Gemnasium, ktorý parsuje mnohé (ale nie všetky) changelogy projektov s otvoreným zdrojovým kódom.

A čo spätne stiahnuté vydania?

Stiahnuté vydania sú verzie, ktoré museli byť neskôr spätne odobraté kvôli vážnej chybe alebo bezpečnostným rizikám. Tieto verzie sa často v changelogu ani neobjavia. Ale mali by sa. Zobrazovať by sa mali takto:

## 0.0.5 - 2014-12-13 [YANKED]

Tag [YANKED] kričí naschvál. Je dôležité, aby si ho ľudia všimli. Keďže je uzavretý zátvorkami, je tiež jednoduchšie ho programovo parsovať.

Mal by sa changelog niekedy prepisovať?

Samozrejme. Vždy sa nájde dobrý dôvod na vylepšenie changelogu. Sám často otváram pull requesty pre pridanie chýbajúceho vydania projektov s otvoreným kódom a neudržiavaným changelogom.

Tiež môže nastať situácia, že v poznámkach k vydaniu určitej verzie sa zabudla spomenúť podstatná zmena. V takom prípade je samozrejme dôležité tento changelog aktualizovať.

Ako môžem prispieť?

Tento dokument nie je úplná pravda; je mojím starostlivo zváženým názorom spolu s informáciami a príkladmi, ktoré som zozbieral.

Je tomu tak preto, aby komunita dosiahla určitý konsenzus. Verím, že diskusia je rovnako dôležitá ako samotný výsledok.

Takže, prosím, prilož ruku k dielu.

Rozhovory

Zúčastnil som sa podcastu The Changelog, kde sme sa rozprávali o tom, prečo by sa správci projektov a prispievatelia mali zaujímať o changelogy a tiež o motivácii za týmto projektom.