diff --git a/source/cs/0.3.0/index.html.haml b/source/cs/0.3.0/index.html.haml new file mode 100644 index 0000000..29cf615 --- /dev/null +++ b/source/cs/0.3.0/index.html.haml @@ -0,0 +1,177 @@ +--- +description: Udržuj Changelog +title: Udržuj Changelog +language: cs +version: 0.3.0 +--- + +:markdown + # Udržuj CHANGELOG + + ## Nenech své kamarády házet do CHANGELOGů™ git logy. + + Version **#{current_page.metadata[:page][:version]}** + + ### Co je to changelog? + Changelog je soubor, který obsahuje organizovaný, chronologicky seřazený + seznam podstatných změn pro každou verzi daného projektu. + +%pre.changelog= File.read("CHANGELOG.md") + +:markdown + ### Co je smyslem changelogu? + Usnadnit uživatelům a přispěvatelům přesné zobrazení podstatných změn, které + byly provedeny mezi jednotlivými vydáními (verzemi) daného projektu. + + ### Proč by mi na tom mělo záležet? + Protože softwarové nástroje jsou pro lidi. Pokud ti na tom nezáleží, tak proč + přispíváš do open source projektů? Určitě musí být v tvém úžasném malém mozku + alespoň jádro (haha!) ochoty. + + [Bavil jsem se s Adamem Stacoviakem a Jerodem Santem na podcastu The Changelog][thechangelog] + (název sedí, co?) o tom proč by na tom mělo vedoucím a přispěvatelům projektů + záležet a o tom jaká motivace je za tímto projektem. Jestli máš chvilku času + (1:06), stojí to za poslech. + + ### Co dělá changelog dobrým? + Výborná otázka, díky za ni. + + Dobrý changelog se drří těchto principů: + + - Je psaný pro lidi, ne pro stroje, takže čitelnost je zásadní. + - Dá se v něm jednoduše odkázat na libovolnou sekci (proto raději Markdown než plain text). + - Jedna pod-sekce za verzi. + - Seznam vydání ve zpětně-chronologickém pořadí (nejnovější navrchu). + - Psaní všech dat ve formátu `RRRR-MM-DD`. (Příklad: `2012-06-02` pro `2. červen 2012`.) Je to mezinárodní, [rozumné](http://xkcd.com/1179/) a nezávislé na jazyce. + - Explicitní uvedení toho, zda projekt dodržuje [Semantické Verzování][semver]. + - Každá verze by měla: + - Uvádět datum vydání ve výše uvedeném formátu. + - Seskupovat změny tak, aby popisovaly dopad na projekt, a to následovně: + - `Added` pro nové funkce. + - `Changed` pro změny v aktuálním fungování. + - `Deprecated` pro dříve stabilní funkce, které budou odstraněny v novějších vydáních a nejsou podporovány. + - `Removed` pro funkce odstraněné v daném vydání. + - `Fixed` pro opravené chyby. + - `Security` pro navržení aktualizace uživatelům v případě bezpečnostních problémů. + + + ### Jak mohu vyžadovanou snahu snížit na minimum? + Vždycky měj nahoře sekci `"Unreleased"`, ve které budou schromažďovány všechny + změny. + + To plní hned dva účely: + + - Lidé uvidí, jaké změny mohou očekávat v následujících vydáních + - V momentu vydání stačí změnit `"Unreleased"` na číslo verze a přidat nový nadpis `"Unreleased"` na vrch dokumentu. + + ### Co zaručeně rozbrečí jednorožce? + Dobrá… Tak si to povíme. + + - **Zkopírování diffu commit logů.** To prostě nedělej, nikomu to nepomůže. + - **Nezdůraznění dále nepodporovaných funcí.** Když lidé aktualizují na novou verzi, mělo by jim být bolestivě jasné, že se něco rozbije. + - **Data v regionálních formátech.** V USA píšou lidé nejdříve měsíc ("06-02-2012" pro 2. června 2012, což nedává *vůbec žádný* smysl), zatímco mnoho lidí ve zbytku světa píše roboticky vypadající verzi "2 June 2012", ale vyslovují to jinak. "2012-06-02" je logicky napsané od největšího po nejmenší celek, nepřekrývá se nesrozumitelně s jinými fomáty data a je to [ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Proto je to doporučovaný formát dat pro changelogy. + + To ale není všechno. Pomoz mi sbírat jednorožčí slzy tím že + [otevřeš issue][issues] nebo pull request. + + ### Existuje pro formát changelogů nějaký standard? + Bohužel ne. Klid. Vím, že se zuřivě snažíš najít ten odkaz na GNU návod jakým + stylem psát changelog, nebo onen dvouodstavcový GNU NEWS soubor, který si říká + "směrnice". Zmíněný GNU návod je sice hezký začátek, ale je smutně naivní. Být + naivní není nic špatného, ale když lidé potřebují radu, málokdy to někomu + pomůže. Obzvlášť, když existuje tolik situací a okrajových případů, se kterými + se musí člověk nějak poprat. + + Tento projekt + [obsahuje něco, co se doufám jednou stane lepší konvencí pro CHANGELOGy][CHANGELOG]. + Nemyslím si, že je momentální stav dostatečně dobrý, a jsem toho názoru, že + jsme jako komunita schopni vymyslet lepší konvence, pokud se budeme snažit + vybrat ty nejlepší praktiky z doopravdových softwarových projektů. + Porozhlédněte se a mějte na paměti, že + [diskuse a návrhy na zlepšení jsou vítány][issues]! + + ### Jak by se měl changelog jmenovat? + Inu, pokud jste to už nepoznali z příkladu výše, `CHANGELOG.md` je zatím ta + nejlepší konvence. + + Některé projekty používají `HISTORY.txt`, `HISTORY.md`, `History.md`, + `NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, + `releases.md`, apod. + + Je v tom binec. Všecha tato jména jen komplikují život lidem, kteří se ten + dokument snaží najít. + + ### Proč lidé jednoduše nepoužívají `git log` diff? + Protože diffy logů jsou plné šumu — přirozeně. Nebyly by vyhovujícím + changelogem ani v hypotetickém projektu vedeném dokonalými lidmi, kteří nikdy + nedělají překlepy, nikdy nezapomínají commitnout nové doubor a nikdy jim + neunikne ani ta nejmenší část refactoringu. Cílem commitu je dokumentovat + jeden miniaturní krok při procesu, ve kterém se kód vyvíjí z jedné podoby do + druhé. Cílem changelogu je dokumentovat podstatné změny mezi těmito podobami. + + Stějně jako je rozdíl mezi dobrými komentáři a samotným kódem, je také rozdíl + mezi changelogem a commitlogem: jeden říká *proč* a druhý jak. + + ### Mohou být changelogy automaticky parsované? + Je to složité, jelikož se lidé uchylují k nejrůznějším formátům a názvům + souborů. + + [Vandamme][vandamme] je Ruby gem vytvořený týmem [Gemnasium][gemnasium], který + parsuje mnoho (ale ne všechny) changelogů open source projektů. + + ### Proč používáš jednou "CHANGELOG" a jindy "changelog"? + "CHANGELOG" je název samotného souboru. Je to třichu křiklavé, ale to už je + historická konvence, kterou se řídí mnoho open source projektů. Příklady + podobných souborů mohou být [`README`][README], [`LICENSE`][LICENSE] a + [`CONTRIBUTING`][CONTRIBUTING]. + + Název psaný kapitálkami (díky kterému se ve starých operačních systémech + soubory držely na nejvyšších pozicích) je používán za účelem upoutání + pozornosti. Vzhledem k tomu, že se jedná o důležitá metadata o projektu a + mohla by být užitečná pro kohokoliv, kdo ho chce používat nebo do něho + přispívat, podobně [open source projektovým odznakům][shields]. + + Když mluvím o "changelogu", myslím tím funkci tohoto souboru: logování změn. + + ### Jak potom vypadají ta vydání, která byla zpětně stažena? + Zpětně stažená vydání jsou verze, které musely být zpětně odebrány kvůli vážné + chybě nebo bezpečnostním rizikům. Tyto verze se často v changelogu ani + neobjevují, ale měly by. Zobrazovat by se měli takto: + + `## 0.0.5 - 2014-12-13 [YANKED]` + + Tag `[YANKED]` je naschvál křiklavý. Je důležité, aby si ho lidé všimli. Díky + tomu, že je v hranatých závorkách je take jednoduší ho parsovat programem. + + ### Měl by se někdy changelog přepisovat? + Jasně. Vždy se najde dobrý důvod pro zlepšení changelogu. Sám často otevírám + pull requesty pro přidání chybějících vydání v open source projektech s + neudržovanými changelogy. + + Je také možné, že zjistíš, že v poznámkách k verzi ve tvém projektu není + zmíněna změna, která něco mohla rozbít. V tom případě jě samozřejmě důležité, + aby byl changelog aktualizován. + + ### Jak mohu přidat ruku k dílu? + Tento dokument není čistá **pravda**; je to můj názor, nad kterým jsem opatrně + uvažoval, v kombinaci s informacemi a příklady, které se mi podařilo získat. + I přesto, že uvádím vlastní [CHANGELOG][] v [repozitáři na GitHubu][gh], + naschvál jsem nevytvořil náležité *vydání* nebo jasný seznam pravidel, kterými + se někdo má řídit (jako to například udělali na [SemVer.org][semver]). + + Je tomu tak proto, že chci aby komunita došla ke společné shodě. Já sám jsem + toho názoru, že diskuse je důležitou součástí finálního výsledku. + + Takže prosím [**přispějte**][gh] svou trochou do mlýna. + + [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/