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..208f7ac --- /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é soubory 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/ diff --git a/source/de/0.3.0/index.html.haml b/source/de/0.3.0/index.html.haml index ed7e8e9..c0d27af 100644 --- a/source/de/0.3.0/index.html.haml +++ b/source/de/0.3.0/index.html.haml @@ -8,32 +8,33 @@ version: 0.3.0 :markdown # Führe ein CHANGELOG - ## Lass deine Freunde nicht CHANGELOGs mit git logs füllen™ + ## Lass Deine Freunde nicht CHANGELOGs mit git logs füllen™ Version **#{current_page.metadata[:page][:version]}** ### Was ist ein Changelog? - Ein Changelog ist eine Datei, welche eine nachgeführte, chronologisch sortierte - Liste aller relevanten Änderungen für jede Version eines Projektes enthält. + Ein Changelog ist eine Datei, welche eine handgepflegte, chronologisch sortierte + Liste aller erheblichen Änderungen enthält, die zwischen Veröffentlichungen (oder Versionen) + des Projekts umgesetzt wurden. %pre.changelog= File.read("CHANGELOG.md") :markdown ### Was ist der Zweck eines Changelogs? - Es für Benutzer und Entwickler einfacher zu machen, die relevanten Änderungen, welche - zwischen Releases (oder Versionen) des Projekts gemacht wurden, zu sehen. + Es Benutzern und Entwicklern einfacher zu machen, gerade die beachtenswerten Änderungen, welche + zwischen Veröffentlichungen (oder Versionen) des Projekts gemacht wurden, zu sehen. - ### Warum sollte ich mich darum kümmern? - Weil Software-Werkzeuge für Menschen gemacht sind. Wenn du dich nicht darum kümmerst, weshalb - beteiligst du dich dann an Open-Source? Wenn du tief in dich gehst, findest du bestimmt + ### Warum sollte mich das kümmern? + Weil Software-Werkzeuge für Menschen gemacht sind. Wenn es Dich nicht kümmert, warum + trägst Du dann zu Open Source bei? Wenn Du tief in Dich gehst, findest Du bestimmt einen kleinen Teil, dem das wichtig ist. Ich [habe mit Adam Stacoviak and Jerod Santo im The Changelog-Podcast][thechangelog] (passt, oder?) darüber gesprochen (Englisch), weshalb sich Entwickler darum kümmern sollten und über die - Beweggründe hinter diesem Projekt. Falls du die Zeit hast (1:06), es lohnt sich, reinzuhören. + Beweggründe hinter diesem Projekt. Falls Du die Zeit hast (1:06), es lohnt sich, reinzuhören. ### Was macht ein gutes Changelog aus? - Schön, dass du fragst. + Schön, dass Du fragst. Ein gutes Changelog hält sich an die folgenden Prinzipien: @@ -59,7 +60,7 @@ version: 0.3.0 Dies verfolgt zwei Ziele: - Man kann sehen, welche Änderungen in den nächsten Releases zu erwarten sind - - Wenn es Zeit für den Release ist, kannst du einfach `"Unreleased"` auf die + - Wenn es Zeit für den Release ist, kannst Du einfach `"Unreleased"` auf die Versionsnummer ändern und einen neuen `"Unreleased"`-Titel oben einfügen. ### Was bringt Einhörner zum weinen? @@ -81,7 +82,7 @@ version: 0.3.0 oder einen Pull-Request. ### Gibt es ein standardisiertes Changelog-Format? - Leider nicht. Beruhige dich. Ich weiss, dass du wie wild nach dem Link für den + Leider nicht. Beruhige Dich. Ich weiss, dass Du wie wild nach dem Link für den GNU Changelog Styleguide oder den zwei Absätze langen GNU NEWS-Datei "Leitfaden" suchst. Der GNU Styleguide ist ein guter Anfang, aber er ist leider sehr naiv. Es ist sicher nichts falsch daran, naiv zu zu sein, aber beim Verfassen eines Leitfadens @@ -90,11 +91,11 @@ version: 0.3.0 Dieses Projekt [enthält das, wovon ich hoffe, dass es zu einer besseren CHANGELOG-Datei-Konvention][CHANGELOG] wird. Ich glaube nicht, dass der status quo gut genug ist, und ich denke, dass wir als Community eine bessere Konvention entwickeln können, wenn wir Bewährtes aus echten - Software-Projekten entnehmen. Schau dich um und denk daran, dass + Software-Projekten entnehmen. Schau Dich um und denk daran, dass [Diskussionen und Verbesserungsvorschläge sehr willkommen sind][issues]! ### Wie soll ich meine Changelog-Datei nennen? - Nun, falls du es noch nicht am Beispiel oben gesehen hast, `CHANGELOG.md` + Nun, falls Du es noch nicht am Beispiel oben gesehen hast, `CHANGELOG.md` ist bisher die beste Konvention. Einige Projekte nutzen auch `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, @@ -122,7 +123,7 @@ version: 0.3.0 [Vandamme][vandamme] ist ein Ruby gem vom [Gemnasium][gemnasium]-Team, welches viele (aber nicht alle) Changelogs von Open-Source-Projekten parsen kann. - ### Wieso schreibst du mal "CHANGELOG" und mal "Changelog"? + ### Wieso schreibst Du mal "CHANGELOG" und mal "Changelog"? "CHANGELOG" ist der Name der Datei selbst. Es ist ein bisschen laut, aber es ist eine historische Konvention, welche von vielen Open-Source-Projekten angewendet wird. Andere Beispiele von ähnlichen Dateien sind [`README`][README], @@ -140,7 +141,7 @@ version: 0.3.0 ### Wie sieht es mit zurückgezogenen Releases aus? Sogenannte "Yanked Releases" sind Versionen, welche wegen schwerwiegenden Bugs oder Sicherheitsproblemen zurückgezogen werden mussten. Häufig kommen - diese im Changelog gar nicht vor. Das sollten sie aber. So solltest du diese + diese im Changelog gar nicht vor. Das sollten sie aber. So solltest Du diese darstellen: `## 0.0.5 - 2014-12-13 [YANKED]` @@ -154,7 +155,7 @@ version: 0.3.0 regelmässig Pull Requests um Open-Source-Projekten mit schlecht gewarteten Changelogs fehlende Releases hinzuzufügen. - Es ist auch möglich, dass du eine wichtige Änderung vergessen hast, in einer + Es ist auch möglich, dass Du eine wichtige Änderung vergessen hast, in einer Version zu erwähnen. Natürlich ist es in diesem Fall wichtig, das Changelog zu aktualisieren.