mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-31 01:34:18 +02:00
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:
parent
0d8d117670
commit
fcce20efff
@ -16,9 +16,8 @@ version: 0.3.0
|
|||||||
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.
|
||||||
|
@ -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.
|
||||||
|
@ -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
|
|
||||||
### What’s the point of a change log?
|
### What’s 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.
|
||||||
|
@ -12,14 +12,13 @@ version: 0.4.0
|
|||||||
|
|
||||||
Version **#{current_page.metadata[:page][:version]}**
|
Version **#{current_page.metadata[:page][:version]}**
|
||||||
|
|
||||||
### What’s a change log?
|
### What’s 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
|
### What’s the point of a changelog?
|
||||||
### What’s 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), it’s a good listen.
|
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.
|
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.
|
- It’s 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.
|
||||||
|
|
||||||
There’s more. Help me collect those unicorn tears by
|
There’s 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 can’t tell from the example above, `CHANGELOG.md` is the
|
Well, if you can’t 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 can’t people just use a `git log` diff?
|
### 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
|
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?
|
||||||
It’s difficult, because people follow wildly different formats and file names.
|
It’s 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**; it’s my carefully considered
|
This document is not the **truth**; it’s my carefully considered
|
||||||
|
@ -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.
|
||||||
|
@ -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 d’un projet
|
version d’un projet
|
||||||
|
|
||||||
%pre.changelog= File.read("CHANGELOG.md")
|
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||||
|
|
||||||
:markdown
|
|
||||||
### Quel est l’intérêt d’un change log ?
|
### Quel est l’intérêt d’un 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
|
||||||
|
@ -13,9 +13,8 @@ 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.
|
||||||
|
@ -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"}
|
||||||
|
@ -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.
|
||||||
|
|
||||||
|
@ -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
|
||||||
|
@ -18,9 +18,8 @@ version: 0.3.0
|
|||||||
хронологическом порядке список значимых изменений для каждой версии проекта с
|
хронологическом порядке список значимых изменений для каждой версии проекта с
|
||||||
открытым исходным кодом.
|
открытым исходным кодом.
|
||||||
|
|
||||||
%pre.changelog= File.read("CHANGELOG.md")
|
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||||
|
|
||||||
:markdown
|
|
||||||
### Для чего нужен лог изменений?
|
### Для чего нужен лог изменений?
|
||||||
|
|
||||||
Чтобы пользователи и контрибьюторы могли с меньшими усилиями точно
|
Чтобы пользователи и контрибьюторы могли с меньшими усилиями точно
|
||||||
|
@ -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.
|
||||||
|
@ -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.
|
||||||
|
@ -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.
|
||||||
|
@ -17,9 +17,8 @@ version: 0.3.0
|
|||||||
这个列表记录所有版本的重大变动。
|
这个列表记录所有版本的重大变动。
|
||||||
|
|
||||||
|
|
||||||
%pre.changelog= File.read("CHANGELOG.md")
|
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||||
|
|
||||||
:markdown
|
|
||||||
### 为何要提供更新日志?
|
### 为何要提供更新日志?
|
||||||
为了让用户和开发人员更好知道每一个版本有哪些区别。
|
为了让用户和开发人员更好知道每一个版本有哪些区别。
|
||||||
|
|
||||||
|
@ -17,9 +17,8 @@ version: 0.3.0
|
|||||||
這個列表記錄所有版本的重大變動。
|
這個列表記錄所有版本的重大變動。
|
||||||
|
|
||||||
|
|
||||||
%pre.changelog= File.read("CHANGELOG.md")
|
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||||
|
|
||||||
:markdown
|
|
||||||
### 為何要提供更新日誌?
|
### 為何要提供更新日誌?
|
||||||
為了讓用戶和開發人員更好知道每一個版本有哪些區別。
|
為了讓用戶和開發人員更好知道每一個版本有哪些區別。
|
||||||
|
|
||||||
|
Loading…
x
Reference in New Issue
Block a user