diff --git a/source/cs/0.3.0/index.html.haml b/source/cs/0.3.0/index.html.haml index 208f7ac..435e2a2 100644 --- a/source/cs/0.3.0/index.html.haml +++ b/source/cs/0.3.0/index.html.haml @@ -13,26 +13,25 @@ version: 0.3.0 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. + 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") +
#{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. + 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 + 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. - + (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. @@ -52,12 +51,12 @@ version: 0.3.0 - `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ů. - + - `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. + Vždycky měj nahoře sekci `"Unreleased"`, ve které budou schromažďovány všechny + změny. To plní hned dva účely: @@ -66,103 +65,103 @@ version: 0.3.0 ### 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 + - **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á + 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 + 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 + 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 + 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`, + 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ů. + Je v tom binec. Všecha tato jména jen komplikují život lidem, kteří se ten + dokument snaží najít. - [Vandamme][vandamme] je Ruby gem vytvořený týmem [Gemnasium][gemnasium], který + ### 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 + "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 + 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. - + + 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 + 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 + 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 + 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. + 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], + 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. + + 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 diff --git a/source/de/0.3.0/index.html.haml b/source/de/0.3.0/index.html.haml index c0d27af..ae3936a 100644 --- a/source/de/0.3.0/index.html.haml +++ b/source/de/0.3.0/index.html.haml @@ -17,9 +17,8 @@ version: 0.3.0 Liste aller erheblichen Änderungen enthält, die zwischen Veröffentlichungen (oder Versionen) des Projekts umgesetzt wurden. -%pre.changelog= File.read("CHANGELOG.md") +
#{File.read("CHANGELOG.md")}-:markdown ### Was ist der Zweck eines Changelogs? Es Benutzern und Entwicklern einfacher zu machen, gerade die beachtenswerten Änderungen, welche zwischen Veröffentlichungen (oder Versionen) des Projekts gemacht wurden, zu sehen. diff --git a/source/en/0.3.0/index.html.haml b/source/en/0.3.0/index.html.haml index 3bbd884..f7cba88 100644 --- a/source/en/0.3.0/index.html.haml +++ b/source/en/0.3.0/index.html.haml @@ -16,9 +16,8 @@ version: 0.3.0 A change log is a file which contains a curated, chronologically ordered list of notable changes for each version of a project. -%pre.changelog= File.read("CHANGELOG.md") +
#{File.read("CHANGELOG.md")}-:markdown ### What’s the point of a change log? To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project. diff --git a/source/en/0.4.0/index.html.haml b/source/en/0.4.0/index.html.haml index 81c6c36..336ec6b 100644 --- a/source/en/0.4.0/index.html.haml +++ b/source/en/0.4.0/index.html.haml @@ -12,14 +12,13 @@ version: 0.4.0 Version **#{current_page.metadata[:page][:version]}** - ### What’s a change log? - A change log is a file which contains a curated, chronologically ordered + ### What’s a changelog? + A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project. -%pre.changelog= File.read("CHANGELOG.md") +
#{File.read("CHANGELOG.md")}-:markdown - ### What’s the point of a change log? + ### What’s the point of a changelog? To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project. @@ -33,10 +32,10 @@ version: 0.4.0 contributors should care, and the motivations behind this project. If you can spare the time (1:06), it’s a good listen. - ### What makes a good change log? + ### What makes a good changelog? I’m glad you asked. - A good change log sticks to these principles: + A good changelog sticks to these principles: - It’s made for humans, not machines, so legibility is crucial. - Easy to link to any section (hence Markdown over plain text). @@ -76,15 +75,15 @@ version: 0.4.0 it differently. "2012-06-02" works logically from largest to smallest, doesn't overlap in ambiguous ways with other date formats, and is an [ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Thus, it - is the recommended date format for change logs. + is the recommended date format for changelogs. There’s more. Help me collect those unicorn tears by [opening an issue][issues] or a pull request. - ### Is there a standard change log format? + ### Is there a standard changelog format? Sadly, no. Calm down. I know you're furiously rushing to find that link - to the GNU change log style guide, or the two-paragraph GNU NEWS file + to the GNU changelog style guide, or the two-paragraph GNU NEWS file "guideline". The GNU style guide is a nice start but it is sadly naive. There's nothing wrong with being naive but when people need guidance it's rarely very helpful. Especially when there are many @@ -96,7 +95,7 @@ version: 0.4.0 real software projects. Please take a look around and remember that [discussions and suggestions for improvements are welcome][issues]! - ### What should the change log file be named? + ### What should the changelog file be named? Well, if you can’t tell from the example above, `CHANGELOG.md` is the best convention so far. @@ -107,24 +106,24 @@ version: 0.4.0 ### Why can’t people just use a `git log` diff? Because log diffs are full of noise — by nature. They could not make a suitable - change log even in a hypothetical project run by perfect humans who never make + changelog even in a hypothetical project run by perfect humans who never make typos, never forget to commit new files, never miss any part of a refactoring. The purpose of a commit is to document one atomic step in the process by which - the code evolves from one state to another. The purpose of a change log is to + the code evolves from one state to another. The purpose of a changelog is to document the noteworthy differences between these states. As is the difference between good comments and the code itself, - so is the difference between a change log and the commit log: + so is the difference between a changelog and the commit log: one describes the *why*, the other the how. - ### Can change logs be automatically parsed? + ### Can changelogs be automatically parsed? It’s difficult, because people follow wildly different formats and file names. [Vandamme][vandamme] is a Ruby gem created by the [Gemnasium][gemnasium] team and which parses - many (but not all) open source project change logs. + many (but not all) open source project changelogs. - ### Why do you alternate between spelling it "CHANGELOG" and "change log"? + ### Why do you alternate between spelling it "CHANGELOG" and "changelog"? "CHANGELOG" is the name of the file itself. It's a bit shouty but it's a historical convention followed by many open source projects. Other examples of similar files include [`README`][README], [`LICENSE`][LICENSE], @@ -135,7 +134,7 @@ version: 0.4.0 metadata about the project, they could be useful to anyone intending to use or contribute to it, much like [open source project badges][shields]. - When I refer to a "change log", I'm talking about the function of this + When I refer to a "changelog", I'm talking about the function of this file: to log changes. ### What about yanked releases? @@ -149,14 +148,14 @@ version: 0.4.0 notice it. Since it's surrounded by brackets it's also easier to parse programmatically. - ### Should you ever rewrite a change log? - Sure. There are always good reasons to improve a change log. I regularly open + ### Should you ever rewrite a changelog? + Sure. There are always good reasons to improve a changelog. I regularly open pull requests to add missing releases to open source projects with unmaintained - change logs. + changelogs. It's also possible you may discover that you forgot to address a breaking change in the notes for a version. It's obviously important for you to update your - change log in this case. + changelog in this case. ### How can I contribute? This document is not the **truth**; it’s my carefully considered diff --git a/source/es-ES/0.3.0/index.html.haml b/source/es-ES/0.3.0/index.html.haml index b46f90e..c30c387 100644 --- a/source/es-ES/0.3.0/index.html.haml +++ b/source/es-ES/0.3.0/index.html.haml @@ -16,9 +16,8 @@ version: 0.3.0 Un registro de cambios o “change log” de ahora en adelante, es un archivo que contiene una lista en orden cronológico sobre los cambios que vamos haciendo en cada reléase (o versión) de nuestro proyecto. -%pre.changelog= File.read("CHANGELOG.md") +
#{File.read("CHANGELOG.md")}-:markdown ### Cuál es el propósito del change log? Para que les sea más fácil a los usuarios y contribuyentes, ver exactamente los cambios notables que se han hecho entre cada versión (o versiones) del proyecto. diff --git a/source/fr/0.3.0/index.html.haml b/source/fr/0.3.0/index.html.haml index 87abdd6..87cfdd0 100644 --- a/source/fr/0.3.0/index.html.haml +++ b/source/fr/0.3.0/index.html.haml @@ -17,9 +17,8 @@ version: 0.3.0 une liste triée chronologiquement des changements notables pour chaque version d’un projet -%pre.changelog= File.read("CHANGELOG.md") +
#{File.read("CHANGELOG.md")}-:markdown ### Quel est l’intérêt d’un change log ? Il permet aux utilisateurs et aux contributeurs de voir plus simplement les changements notables qui ont été réalisés entre chaque publication @@ -181,7 +180,7 @@ version: 0.3.0 J'ouvre souvent des pull requests pour ajouter des publications manquantes sur des projets open source avec des change logs non-maintenus. - Il est aussi possible que vous découvriez que vous aviez oublié de mentionner + Il est aussi possible que vous découvriez que vous aviez oublié de mentionner un changement majeur dans les notes de version. Il est évidemment important que vous mettiez votre change log à jour dans ce cas. diff --git a/source/it-IT/0.3.0/index.html.haml b/source/it-IT/0.3.0/index.html.haml index 543a6fe..74c2e9f 100644 --- a/source/it-IT/0.3.0/index.html.haml +++ b/source/it-IT/0.3.0/index.html.haml @@ -13,17 +13,16 @@ language: it-IT Un change log è un file che contiene una lista curata e ordinata cronologicamente delle modifiche degne di nota per ogni versione di un progetto. -%pre.changelog= File.read("CHANGELOG.md") +
#{File.read("CHANGELOG.md")}-:markdown ### A cosa serve un change log? - Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche + Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche importanti sono state fatte tra ogni release (o versione) del progetto. ### Perché dovrebbe importarmi? Perché gli strumenti software sono fatti per le persone. Se non ti importa, perché contribuisci all'open source? - Di certo ci deve essere un "kernel" (ha!) di interesse + Di certo ci deve essere un "kernel" (ha!) di interesse da qualche parte in quel tuo amorevole cervello. [Nel podcast "The Changelog" con Adam Stacoviak e Jerod Santo][thechangelog] @@ -85,9 +84,9 @@ language: it-IT è raramente d'aiuto. Specialmente se ci sono molte situazioni e casi limite da gestire. Questo progetto [contiene ciò che spero diventerà una migliore convenzione per i file CHANGELOG][CHANGELOG]. - Non credo che lo status quo sia sufficientemente buono, e penso che noi, come comunità, + Non credo che lo status quo sia sufficientemente buono, e penso che noi, come comunità, possiamo arrivare a convenzioni migliori se tentiamo di estrarre le pratiche migliori - da progetti software reali. Vi consiglio di guardarvi intorno e ricordare che + da progetti software reali. Vi consiglio di guardarvi intorno e ricordare che [ogni discussione e suggerimento per migliorare sono sempre benvenuti][issues]! ### Come si dovrebbe chiamare il file contenente il change log? @@ -104,7 +103,7 @@ language: it-IT di digitazione, non dimenticano mai di fare commit dei nuovi file, non dimenticano mai alcuna parte di un refactoring. Lo scopo di un commit è di documentare un passo atomico nel processo di evoluzione del codice - da uno stato ad un altro. Lo scopo di un change log è di documentare le differenze + da uno stato ad un altro. Lo scopo di un change log è di documentare le differenze degne di nota tra questi stati. La differenza tra un change log e un commit log è @@ -113,18 +112,18 @@ language: it-IT ### Si possono analizzare automaticamente i change log? È difficile, perché le persone usano formati e nomi di file profondamente diversi. - + [Vandamme][vandamme] è una Ruby gem creata dal team [Gemnasium][gemnasium] ed è in grado di fare il parsing dei change log di molti (ma non tutti) i progetti open source. ### Perché si alterna tra i nomi "CHANGELOG" e "change log"? - "CHANGELOG" è il nome del file. È un po' invadente ma è una + "CHANGELOG" è il nome del file. È un po' invadente ma è una convenzione storica seguita da molti progetti open source. Altri esempi di file simili includono [`README`][README], [`LICENSE`][LICENSE], e [`CONTRIBUTING`][CONTRIBUTING]. - I nomi in maiuscolo (che su vecchi sistemi operativi erano ordinati per primi) + I nomi in maiuscolo (che su vecchi sistemi operativi erano ordinati per primi) vengono usati per attirare l'attenzione su di essi. Poiché sono metadati importanti relativi al progetto, possono essere utili per chiunque voglia usarlo o contribuire ad esso, un po' come i [badge dei progetti open source][shields]. @@ -158,7 +157,7 @@ language: it-IT ho volutamente evitato di creare una *release* o una chiara lista di regole da seguire (come fa, ad esempio, [SemVer.org][semver]). - Questo è perché voglio che la nostra comunità raggiunga un consenso. Credo che + Questo è perché voglio che la nostra comunità raggiunga un consenso. Credo che la discussione sia importante almeno quanto il risultato finale. Quindi per favore [**partecipate**][gh]. diff --git a/source/layouts/layout.html.haml b/source/layouts/layout.html.haml index 4b44ab3..10b0382 100644 --- a/source/layouts/layout.html.haml +++ b/source/layouts/layout.html.haml @@ -52,6 +52,9 @@ for now and = link_to "help translate ", "https://github.com/olivierlacan/keep-a-changelog/issues" it. + + - content = Haml::Filters::Code.render(yield) + = Redcarpet::Markdown.new(Redcarpet::Render::HTML_TOC.new(nesting_level: 5), { with_toc_data: true }).render(content).html_safe = yield %footer.clearfix{role: "banner"} diff --git a/source/pl-PL/0.3.0/index.html.haml b/source/pl-PL/0.3.0/index.html.haml index e997e81..9592638 100644 --- a/source/pl-PL/0.3.0/index.html.haml +++ b/source/pl-PL/0.3.0/index.html.haml @@ -15,9 +15,8 @@ version: 0.3.0 ### Czym jest changelog? Changelog, inaczej rejestr zmian lub historia zmian, to plik zawierający chronologicznie uporządkowaną listę istotnych zmian dla każdej wersji projektu. -%pre.changelog= File.read("CHANGELOG.md") +
#{File.read("CHANGELOG.md")}-:markdown ### Co jest celem prowadzenia changelogu? Changelog pomaga użytkownikom zrozumieć, jakie znaczące zmiany zostały wprowadzone w każdej wersji projektu. diff --git a/source/pt-BR/0.3.0/index.html.haml b/source/pt-BR/0.3.0/index.html.haml index 4a8207f..0c0a477 100644 --- a/source/pt-BR/0.3.0/index.html.haml +++ b/source/pt-BR/0.3.0/index.html.haml @@ -18,9 +18,8 @@ version: 0.3.0 cronologicamente, de mudanças significativas para cada versão de um projeto open source. -%pre.changelog= File.read("CHANGELOG.md") +
#{File.read("CHANGELOG.md")}-:markdown ### Para que serve um *change log*? Para facilitar para os usuários e contribuidores verem precisamente quais @@ -101,15 +100,15 @@ version: 0.3.0 Infelizmente, não. Calma. Eu sei que você está indo impetuosamente achar aquele link do guia de estilo de *change log* GNU, ou o arquivo "guideline" - de dois paragráfos de GNU NEWS. O estilo GNU é um bom começo mas é ingênuo. - Não há nada de errado em ser ingênuo mas quando as pessoas precisam de - orientação isso raramente ajuda. Especialmente quando existem muitas + de dois paragráfos de GNU NEWS. O estilo GNU é um bom começo mas é ingênuo. + Não há nada de errado em ser ingênuo mas quando as pessoas precisam de + orientação isso raramente ajuda. Especialmente quando existem muitas situações excepcionais e casos extremos com os quais se deve lidar. Este projeto [contém o que eu espero se tornar um melhor padrão de arquivo CHANGELOG][CHANGELOG]. Não acho que o status é bom o suficiente, e acho que como uma comunidade nós podemos definir melhores padrões se tentarmos extrair - boas práticas de projetos de software reais. Então por favor dê um olhada e + boas práticas de projetos de software reais. Então por favor dê um olhada e lembre que [discussões e sugestões para melhorias são bem-vindas][issues]! ### Qual deve ser o nome do arquivo *change log*? @@ -124,7 +123,7 @@ version: 0.3.0 É uma bagunça. Todos esses nome só dificultam que as pessoas o achem. ### Por quê as pessoas não podem simplesmente utilizar `git log`? - + Porque os logs do Git são cheios de ruído — por natureza. Eles não poderiam escrever um change log adequado mesmo em um projeto hipotético desenvolvido por humanos perfeitos que nunca cometem erros de grafia, nunca esquecem de @@ -134,7 +133,7 @@ version: 0.3.0 change log é documentar diferenças notáveis entre estes estados. Assim como são as diferenças entre bons comentários e o próprio código, há - a diferença entre o change log e o commit log: um descreve o porquê e o + a diferença entre o change log e o commit log: um descreve o porquê e o outro o como. ### Podem os *change logs* ser automaticamente interpretados? @@ -172,13 +171,13 @@ version: 0.3.0 A tag `[YANKED]` é chamativa por uma razão. É importante que as pessoas a notem. E já que é cercada por colchetes é mais fácil detectá-la programaticamente. - + ### Se você deveria reescrever um change log? - + Claro. Sempre existem boas razões para melhorar um change log. Eu abro os pull requests regularmente para adicionar releases que faltam a projetos open source com change logs sem manutenção. - + É também possível que você descubra que esqueceu de registrar uma mudança crucial nas anotações de uma versão. É obviamente importante que você atualize seu change log neste caso. diff --git a/source/ru/0.3.0/index.html.haml b/source/ru/0.3.0/index.html.haml index 23ffa88..6e7a5ff 100644 --- a/source/ru/0.3.0/index.html.haml +++ b/source/ru/0.3.0/index.html.haml @@ -18,9 +18,8 @@ version: 0.3.0 хронологическом порядке список значимых изменений для каждой версии проекта с открытым исходным кодом. -%pre.changelog= File.read("CHANGELOG.md") +
#{File.read("CHANGELOG.md")}-:markdown ### Для чего нужен лог изменений? Чтобы пользователи и контрибьюторы могли с меньшими усилиями точно diff --git a/source/sl/0.3.0/index.html.haml b/source/sl/0.3.0/index.html.haml index 73b11c3..a8fa5eb 100644 --- a/source/sl/0.3.0/index.html.haml +++ b/source/sl/0.3.0/index.html.haml @@ -16,9 +16,8 @@ version: 0.3.0 Dnevnik sprememb je datoteka, ki vsebuje kuriran, kronološko urejen seznam opaznih sprememb za vsako verzijo projekta. -%pre.changelog= File.read("CHANGELOG.md") +
#{File.read("CHANGELOG.md")}-:markdown ### 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. diff --git a/source/sv/0.3.0/index.html.haml b/source/sv/0.3.0/index.html.haml index d5004f6..f9dcdef 100644 --- a/source/sv/0.3.0/index.html.haml +++ b/source/sv/0.3.0/index.html.haml @@ -16,9 +16,8 @@ version: 0.3.0 En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad lista över ändringar för varje version av ett projekt. -%pre.changelog= File.read("CHANGELOG.md") +
#{File.read("CHANGELOG.md")}-:markdown ### Vad är meningen med en ändringslogg? För att göra det enkelt för användare och medarbetare att se exakt vilka viktiga ändringar som har gjorts mellan varje utgåva (eller version) av projektet. diff --git a/source/tr-TR/0.3.0/index.html.haml b/source/tr-TR/0.3.0/index.html.haml index a08e66b..60c61a4 100644 --- a/source/tr-TR/0.3.0/index.html.haml +++ b/source/tr-TR/0.3.0/index.html.haml @@ -14,9 +14,8 @@ version: 0.3.0 Değişiklik kayıtları bir proje için özel olarak hazırlanmış, tarihsel sıralamayla sıralanmış, önemli değişikliklerin bir bütünüdür. -%pre.changelog= File.read("CHANGELOG.md") +
#{File.read("CHANGELOG.md")}-:markdown ### Değişikliklerin kayıtlarını tutmanın anlamı ne? Bir projenin kullanıcılarının ya da katılımcılarının, dağıtımlar (ya da sürümler) arasındaki tam olarak hangi önemli değişikliklerin olduğunu takip edebilmelerini sağlar. @@ -90,7 +89,7 @@ version: 0.3.0 Mevcut durumun çok iyi olduğunu düşünmüyorum, ve topluluk olarak, gerçek yazılım projelerinden iyi pratikleri toplayarak bundan daha iyisini yapabiliriz. Lütfen etrafa bir göz gezdirin ve unutmayın [gelişme yolunda tartışmalara ve önerilere her zaman açığız][issues]! - + ### Değişiklik kayıtlarının dosya ismi ne olmalı? Eh, üstteki örnekten çıkartamadıysanız eğer, `CHANGELOG.md` şu ana kadarki en iyi çözüm. @@ -159,7 +158,7 @@ version: 0.3.0 [GitHub repo][gh]sunda güncel bir [CHANGELOG][] sağlıyor olsam da, özellikle bir *sürüm* ya da ([SemVer.org][semver] benzeri) takip edilecek kurallar oluşturmadım. - + Bunu istememin sebebi topluluğun ortak bir paydada buluşmasını istememdir. İnanıyorum ki tartışmanın kendisi de sonucu kadar önemli. diff --git a/source/zh-CN/0.3.0/index.html.haml b/source/zh-CN/0.3.0/index.html.haml index 910bf87..353daa3 100644 --- a/source/zh-CN/0.3.0/index.html.haml +++ b/source/zh-CN/0.3.0/index.html.haml @@ -17,9 +17,8 @@ version: 0.3.0 这个列表记录所有版本的重大变动。 -%pre.changelog= File.read("CHANGELOG.md") +
#{File.read("CHANGELOG.md")}-:markdown ### 为何要提供更新日志? 为了让用户和开发人员更好知道每一个版本有哪些区别。 diff --git a/source/zh-TW/0.3.0/index.html.haml b/source/zh-TW/0.3.0/index.html.haml index 2bf8a50..17210bc 100644 --- a/source/zh-TW/0.3.0/index.html.haml +++ b/source/zh-TW/0.3.0/index.html.haml @@ -17,9 +17,8 @@ version: 0.3.0 這個列表記錄所有版本的重大變動。 -%pre.changelog= File.read("CHANGELOG.md") +
#{File.read("CHANGELOG.md")}-:markdown ### 為何要提供更新日誌? 為了讓用戶和開發人員更好知道每一個版本有哪些區別。