Stop using weird Haml break for changelog preview

It’s really not worth the double filter call and I’m sure I can find
some way to use Middleman to extract this into a method.
This commit is contained in:
Olivier Lacan 2017-04-05 05:27:12 -04:00
parent 0d8d117670
commit fcce20efff
16 changed files with 137 additions and 149 deletions

View File

@ -13,26 +13,25 @@ version: 0.3.0
Version **#{current_page.metadata[:page][:version]}** Version **#{current_page.metadata[:page][:version]}**
### Co je to changelog? ### Co je to changelog?
Changelog je soubor, který obsahuje organizovaný, chronologicky seřazený Changelog je soubor, který obsahuje organizovaný, chronologicky seřazený
seznam podstatných změn pro každou verzi daného projektu. seznam podstatných změn pro každou verzi daného projektu.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Co je smyslem changelogu? ### Co je smyslem changelogu?
Usnadnit uživatelům a přispěvatelům přesné zobrazení podstatných změn, které 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. byly provedeny mezi jednotlivými vydáními (verzemi) daného projektu.
### Proč by mi na tom mělo záležet? ### 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č 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. alespoň jádro (haha!) ochoty.
[Bavil jsem se s Adamem Stacoviakem a Jerodem Santem na podcastu The Changelog][thechangelog] [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ů (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 záležet a o tom jaká motivace je za tímto projektem. Jestli máš chvilku času
(1:06), stojí to za poslech. (1:06), stojí to za poslech.
### Co dělá changelog dobrým? ### Co dělá changelog dobrým?
Výborná otázka, díky za ni. 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. - `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í. - `Removed` pro funkce odstraněné v daném vydání.
- `Fixed` pro opravené chyby. - `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? ### 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 Vždycky měj nahoře sekci `"Unreleased"`, ve které budou schromažďovány všechny
změny. změny.
To plní hned dva účely: To plní hned dva účely:
@ -66,103 +65,103 @@ version: 0.3.0
### Co zaručeně rozbrečí jednorožce? ### Co zaručeně rozbrečí jednorožce?
Dobrá… Tak si to povíme. Dobrá… Tak si to povíme.
- **Zkopírování diffu commit logů.** To prostě nedělej, nikomu to nepomůže. - **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. - **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. - **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 To ale není všechno. Pomoz mi sbírat jednorožčí slzy tím že
[otevřeš issue][issues] nebo pull request. [otevřeš issue][issues] nebo pull request.
### Existuje pro formát changelogů nějaký standard? ### 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 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á 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 "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 pomůže. Obzvlášť, když existuje tolik situací a okrajových případů, se kterými
se musí člověk nějak poprat. se musí člověk nějak poprat.
Tento projekt Tento projekt
[obsahuje něco, co se doufám jednou stane lepší konvencí pro CHANGELOGy][CHANGELOG]. [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 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 jsme jako komunita schopni vymyslet lepší konvence, pokud se budeme snažit
vybrat ty nejlepší praktiky z doopravdových softwarových projektů. vybrat ty nejlepší praktiky z doopravdových softwarových projektů.
Porozhlédněte se a mějte na paměti, že Porozhlédněte se a mějte na paměti, že
[diskuse a návrhy na zlepšení jsou vítány][issues]! [diskuse a návrhy na zlepšení jsou vítány][issues]!
### Jak by se měl changelog jmenovat? ### Jak by se měl changelog jmenovat?
Inu, pokud jste to už nepoznali z příkladu výše, `CHANGELOG.md` je zatím ta Inu, pokud jste to už nepoznali z příkladu výše, `CHANGELOG.md` je zatím ta
nejlepší konvence. nejlepší konvence.
Některé projekty používají `HISTORY.txt`, `HISTORY.md`, `History.md`, Některé projekty používají `HISTORY.txt`, `HISTORY.md`, `History.md`,
`NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`,
`releases.md`, apod. `releases.md`, apod.
Je v tom binec. Všecha tato jména jen komplikují život lidem, kteří se ten Je v tom binec. Všecha tato jména jen komplikují život lidem, kteří se ten
dokument snaží najít. 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ý ### 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ů. parsuje mnoho (ale ne všechny) changelogů open source projektů.
### Proč používáš jednou "CHANGELOG" a jindy "changelog"? ### 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 "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 historická konvence, kterou se řídí mnoho open source projektů. Příklady
podobných souborů mohou být [`README`][README], [`LICENSE`][LICENSE] a podobných souborů mohou být [`README`][README], [`LICENSE`][LICENSE] a
[`CONTRIBUTING`][CONTRIBUTING]. [`CONTRIBUTING`][CONTRIBUTING].
Název psaný kapitálkami (díky kterému se ve starých operačních systémech 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í 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 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 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]. 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? ### 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é 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 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: neobjevují, ale měly by. Zobrazovat by se měli takto:
`## 0.0.5 - 2014-12-13 [YANKED]` `## 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. tomu, že je v hranatých závorkách je take jednoduší ho parsovat programem.
### Měl by se někdy changelog přepisovat? ### 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 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 pull requesty pro přidání chybějících vydání v open source projektech s
neudržovanými changelogy. neudržovanými changelogy.
Je také možné, že zjistíš, že v poznámkách k verzi ve tvém projektu není 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é, 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. aby byl changelog aktualizován.
### Jak mohu přidat ruku k dílu? ### Jak mohu přidat ruku k dílu?
Tento dokument není čistá **pravda**; je to můj názor, nad kterým jsem opatrně 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. 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], 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 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]). 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 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. 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. 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 [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
[CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md

View File

@ -17,9 +17,8 @@ version: 0.3.0
Liste aller erheblichen Änderungen enthält, die zwischen Veröffentlichungen (oder Versionen) Liste aller erheblichen Änderungen enthält, die zwischen Veröffentlichungen (oder Versionen)
des Projekts umgesetzt wurden. des Projekts umgesetzt wurden.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Was ist der Zweck eines Changelogs? ### Was ist der Zweck eines Changelogs?
Es Benutzern und Entwicklern einfacher zu machen, gerade die beachtenswerten Änderungen, welche Es Benutzern und Entwicklern einfacher zu machen, gerade die beachtenswerten Änderungen, welche
zwischen Veröffentlichungen (oder Versionen) des Projekts gemacht wurden, zu sehen. zwischen Veröffentlichungen (oder Versionen) des Projekts gemacht wurden, zu sehen.

View File

@ -16,9 +16,8 @@ version: 0.3.0
A change log is a file which contains a curated, chronologically ordered A change log is a file which contains a curated, chronologically ordered
list of notable changes for each version of a project. list of notable changes for each version of a project.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Whats the point of a change log? ### Whats the point of a change log?
To make it easier for users and contributors to see precisely what 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. notable changes have been made between each release (or version) of the project.

View File

@ -12,14 +12,13 @@ version: 0.4.0
Version **#{current_page.metadata[:page][:version]}** Version **#{current_page.metadata[:page][:version]}**
### Whats a change log? ### Whats a changelog?
A change log is a file which contains a curated, chronologically ordered A changelog is a file which contains a curated, chronologically ordered
list of notable changes for each version of a project. list of notable changes for each version of a project.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown ### Whats the point of a changelog?
### Whats the point of a change log?
To make it easier for users and contributors to see precisely what 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. 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. contributors should care, and the motivations behind this project.
If you can spare the time (1:06), its a good listen. If you can spare the time (1:06), its a good listen.
### What makes a good change log? ### What makes a good changelog?
Im glad you asked. Im glad you asked.
A good change log sticks to these principles: A good changelog sticks to these principles:
- Its made for humans, not machines, so legibility is crucial. - Its made for humans, not machines, so legibility is crucial.
- Easy to link to any section (hence Markdown over plain text). - 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 it differently. "2012-06-02" works logically from largest to smallest, doesn't
overlap in ambiguous ways with other date formats, and is an overlap in ambiguous ways with other date formats, and is an
[ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Thus, it [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.
Theres more. Help me collect those unicorn tears by Theres more. Help me collect those unicorn tears by
[opening an issue][issues] [opening an issue][issues]
or a pull request. 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 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. "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 There's nothing wrong with being naive but when people need
guidance it's rarely very helpful. Especially when there are many 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 real software projects. Please take a look around and remember that
[discussions and suggestions for improvements are welcome][issues]! [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 cant tell from the example above, `CHANGELOG.md` is the Well, if you cant tell from the example above, `CHANGELOG.md` is the
best convention so far. best convention so far.
@ -107,24 +106,24 @@ version: 0.4.0
### Why cant people just use a `git log` diff? ### Why cant people just use a `git log` diff?
Because log diffs are full of noise — by nature. They could not make a suitable 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. 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 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. document the noteworthy differences between these states.
As is the difference between good comments and the code itself, 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. one describes the *why*, the other the how.
### Can change logs be automatically parsed? ### Can changelogs be automatically parsed?
Its difficult, because people follow wildly different formats and file names. Its difficult, because people follow wildly different formats and file names.
[Vandamme][vandamme] is a Ruby gem [Vandamme][vandamme] is a Ruby gem
created by the [Gemnasium][gemnasium] team and which parses 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 "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 historical convention followed by many open source projects. Other
examples of similar files include [`README`][README], [`LICENSE`][LICENSE], 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 metadata about the project, they could be useful to anyone intending to use
or contribute to it, much like [open source project badges][shields]. 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. file: to log changes.
### What about yanked releases? ### 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 notice it. Since it's surrounded by brackets it's also easier to parse
programmatically. programmatically.
### Should you ever rewrite a change log? ### Should you ever rewrite a changelog?
Sure. There are always good reasons to improve a change log. I regularly open 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 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 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 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? ### How can I contribute?
This document is not the **truth**; its my carefully considered This document is not the **truth**; its my carefully considered

View File

@ -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. 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") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Cuál es el propósito del change log? ### 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. 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.

View File

@ -17,9 +17,8 @@ version: 0.3.0
une liste triée chronologiquement des changements notables pour chaque une liste triée chronologiquement des changements notables pour chaque
version dun projet version dun projet
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Quel est lintérêt dun change log ? ### Quel est lintérêt dun change log ?
Il permet aux utilisateurs et aux contributeurs de voir plus simplement Il permet aux utilisateurs et aux contributeurs de voir plus simplement
les changements notables qui ont été réalisés entre chaque publication 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 J'ouvre souvent des pull requests pour ajouter des publications manquantes sur
des projets open source avec des change logs non-maintenus. 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 un changement majeur dans les notes de version. Il est évidemment important
que vous mettiez votre change log à jour dans ce cas. que vous mettiez votre change log à jour dans ce cas.

View File

@ -13,17 +13,16 @@ language: it-IT
Un change log è un file che contiene una lista curata e ordinata cronologicamente Un change log è un file che contiene una lista curata e ordinata cronologicamente
delle modifiche degne di nota per ogni versione di un progetto. delle modifiche degne di nota per ogni versione di un progetto.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### A cosa serve un change log? ### 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. importanti sono state fatte tra ogni release (o versione) del progetto.
### Perché dovrebbe importarmi? ### Perché dovrebbe importarmi?
Perché gli strumenti software sono fatti per le persone. Perché gli strumenti software sono fatti per le persone.
Se non ti importa, perché contribuisci all'open source? 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. da qualche parte in quel tuo amorevole cervello.
[Nel podcast "The Changelog" con Adam Stacoviak e Jerod Santo][thechangelog] [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. è 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]. 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 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]! [ogni discussione e suggerimento per migliorare sono sempre benvenuti][issues]!
### Come si dovrebbe chiamare il file contenente il change log? ### 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 di digitazione, non dimenticano mai di fare commit dei nuovi file, non dimenticano mai
alcuna parte di un refactoring. alcuna parte di un refactoring.
Lo scopo di un commit è di documentare un passo atomico nel processo di evoluzione del codice 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. degne di nota tra questi stati.
La differenza tra un change log e un commit log è La differenza tra un change log e un commit log è
@ -113,18 +112,18 @@ language: it-IT
### Si possono analizzare automaticamente i change log? ### Si possono analizzare automaticamente i change log?
È difficile, perché le persone usano formati e nomi di file profondamente diversi. È difficile, perché le persone usano formati e nomi di file profondamente diversi.
[Vandamme][vandamme] è una Ruby gem [Vandamme][vandamme] è una Ruby gem
creata dal team [Gemnasium][gemnasium] ed è in grado di fare il parsing dei creata dal team [Gemnasium][gemnasium] ed è in grado di fare il parsing dei
change log di molti (ma non tutti) i progetti open source. change log di molti (ma non tutti) i progetti open source.
### Perché si alterna tra i nomi "CHANGELOG" e "change log"? ### 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. convenzione storica seguita da molti progetti open source.
Altri esempi di file simili includono [`README`][README], [`LICENSE`][LICENSE], Altri esempi di file simili includono [`README`][README], [`LICENSE`][LICENSE],
e [`CONTRIBUTING`][CONTRIBUTING]. 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 vengono usati per attirare l'attenzione su di essi. Poiché sono metadati
importanti relativi al progetto, possono essere utili per chiunque voglia usarlo 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]. 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 ho volutamente evitato di creare una *release* o una chiara lista di regole
da seguire (come fa, ad esempio, [SemVer.org][semver]). 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. la discussione sia importante almeno quanto il risultato finale.
Quindi per favore [**partecipate**][gh]. Quindi per favore [**partecipate**][gh].

View File

@ -52,6 +52,9 @@
for now and for now and
= link_to "help translate ", "https://github.com/olivierlacan/keep-a-changelog/issues" = link_to "help translate ", "https://github.com/olivierlacan/keep-a-changelog/issues"
it. 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 = yield
%footer.clearfix{role: "banner"} %footer.clearfix{role: "banner"}

View File

@ -15,9 +15,8 @@ version: 0.3.0
### Czym jest changelog? ### 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. 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") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Co jest celem prowadzenia changelogu? ### Co jest celem prowadzenia changelogu?
Changelog pomaga użytkownikom zrozumieć, jakie znaczące zmiany zostały wprowadzone w każdej wersji projektu. Changelog pomaga użytkownikom zrozumieć, jakie znaczące zmiany zostały wprowadzone w każdej wersji projektu.

View File

@ -18,9 +18,8 @@ version: 0.3.0
cronologicamente, de mudanças significativas para cada versão de um projeto cronologicamente, de mudanças significativas para cada versão de um projeto
open source. open source.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Para que serve um *change log*? ### Para que serve um *change log*?
Para facilitar para os usuários e contribuidores verem precisamente quais 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 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" 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. 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 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 orientação isso raramente ajuda. Especialmente quando existem muitas
situações excepcionais e casos extremos com os quais se deve lidar. 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 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 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 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]! lembre que [discussões e sugestões para melhorias são bem-vindas][issues]!
### Qual deve ser o nome do arquivo *change log*? ### 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. É uma bagunça. Todos esses nome só dificultam que as pessoas o achem.
### Por quê as pessoas não podem simplesmente utilizar `git log`? ### 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 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 escrever um change log adequado mesmo em um projeto hipotético desenvolvido
por humanos perfeitos que nunca cometem erros de grafia, nunca esquecem de 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. 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á 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. outro o como.
### Podem os *change logs* ser automaticamente interpretados? ### 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 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 notem. E já que é cercada por colchetes é mais fácil detectá-la
programaticamente. programaticamente.
### Se você deveria reescrever um change log? ### Se você deveria reescrever um change log?
Claro. Sempre existem boas razões para melhorar um change log. Eu abro os pull 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 requests regularmente para adicionar releases que faltam a projetos open source
com change logs sem manutenção. com change logs sem manutenção.
É também possível que você descubra que esqueceu de registrar uma mudança É 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 crucial nas anotações de uma versão. É obviamente importante que você atualize
seu change log neste caso. seu change log neste caso.

View File

@ -18,9 +18,8 @@ version: 0.3.0
хронологическом порядке список значимых изменений для каждой версии проекта с хронологическом порядке список значимых изменений для каждой версии проекта с
открытым исходным кодом. открытым исходным кодом.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Для чего нужен лог изменений? ### Для чего нужен лог изменений?
Чтобы пользователи и контрибьюторы могли с меньшими усилиями точно Чтобы пользователи и контрибьюторы могли с меньшими усилиями точно

View File

@ -16,9 +16,8 @@ version: 0.3.0
Dnevnik sprememb je datoteka, ki vsebuje kuriran, kronološko urejen Dnevnik sprememb je datoteka, ki vsebuje kuriran, kronološko urejen
seznam opaznih sprememb za vsako verzijo projekta. seznam opaznih sprememb za vsako verzijo projekta.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Kaj je smisel dnevnika sprememb? ### Kaj je smisel dnevnika sprememb?
Za poenostavitev, da uporabniki in prispevajoči sodelavci natančno vidijo, katere Za poenostavitev, da uporabniki in prispevajoči sodelavci natančno vidijo, katere
opazne spremembe so bile narejene med vsako izdajo (ali verzijo) projekta. opazne spremembe so bile narejene med vsako izdajo (ali verzijo) projekta.

View File

@ -16,9 +16,8 @@ version: 0.3.0
En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad
lista över ändringar för varje version av ett projekt. lista över ändringar för varje version av ett projekt.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Vad är meningen med en ändringslogg? ### Vad är meningen med en ändringslogg?
För att göra det enkelt för användare och medarbetare att se exakt vilka 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. viktiga ändringar som har gjorts mellan varje utgåva (eller version) av projektet.

View File

@ -14,9 +14,8 @@ version: 0.3.0
Değişiklik kayıtları bir proje için özel olarak hazırlanmış, tarihsel sıralamayla 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. sıralanmış, önemli değişikliklerin bir bütünüdür.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Değişikliklerin kayıtlarını tutmanın anlamı ne? ### 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) 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. 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 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 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]! 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ı? ### Değişiklik kayıtlarının dosya ismi ne olmalı?
Eh, üstteki örnekten çıkartamadıysanız eğer, `CHANGELOG.md` şu ana kadarki Eh, üstteki örnekten çıkartamadıysanız eğer, `CHANGELOG.md` şu ana kadarki
en iyi çözüm. 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 [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 bir *sürüm* ya da ([SemVer.org][semver] benzeri) takip edilecek kurallar
oluşturmadım. oluşturmadım.
Bunu istememin sebebi topluluğun ortak bir paydada buluşmasını istememdir. Bunu istememin sebebi topluluğun ortak bir paydada buluşmasını istememdir.
İnanıyorum ki tartışmanın kendisi de sonucu kadar önemli. İnanıyorum ki tartışmanın kendisi de sonucu kadar önemli.

View File

@ -17,9 +17,8 @@ version: 0.3.0
这个列表记录所有版本的重大变动。 这个列表记录所有版本的重大变动。
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### 为何要提供更新日志? ### 为何要提供更新日志?
为了让用户和开发人员更好知道每一个版本有哪些区别。 为了让用户和开发人员更好知道每一个版本有哪些区别。

View File

@ -17,9 +17,8 @@ version: 0.3.0
這個列表記錄所有版本的重大變動。 這個列表記錄所有版本的重大變動。
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### 為何要提供更新日誌? ### 為何要提供更新日誌?
為了讓用戶和開發人員更好知道每一個版本有哪些區別。 為了讓用戶和開發人員更好知道每一個版本有哪些區別。