mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-29 08:44:16 +02:00
Merge pull request #110 from olivierlacan/versioning
Start versioning from 0.3.0
This commit is contained in:
Olivier Lacan
GitHub
commit
8bed7d4478
1
.gitignore
vendored
1
.gitignore
vendored
@ -3,3 +3,4 @@
|
||||
/.cache
|
||||
/.sass-cache
|
||||
/build
|
||||
/_site
|
||||
|
||||
6
Gemfile
6
Gemfile
@ -1,12 +1,12 @@
|
||||
source "https://rubygems.org"
|
||||
|
||||
gem "addressable"
|
||||
gem "middleman", "~>3.4.0"
|
||||
gem "middleman", "~> 3.4.0"
|
||||
gem "middleman-autoprefixer"
|
||||
gem "middleman-blog"
|
||||
gem "middleman-livereload"
|
||||
gem "middleman-minify-html"
|
||||
gem "middleman-syntax"
|
||||
gem 'middleman-gh-pages'
|
||||
|
||||
gem "middleman-gh-pages"
|
||||
gem "redcarpet"
|
||||
gem "pry"
|
||||
|
||||
10
Gemfile.lock
10
Gemfile.lock
@ -18,6 +18,7 @@ GEM
|
||||
rack-test (>= 0.5.4)
|
||||
xpath (~> 2.0)
|
||||
chunky_png (1.3.4)
|
||||
coderay (1.1.1)
|
||||
coffee-script (2.4.1)
|
||||
coffee-script-source
|
||||
execjs
|
||||
@ -54,6 +55,7 @@ GEM
|
||||
listen (3.0.3)
|
||||
rb-fsevent (>= 0.9.3)
|
||||
rb-inotify (>= 0.9)
|
||||
method_source (0.8.2)
|
||||
middleman (3.4.0)
|
||||
coffee-script (~> 2.2)
|
||||
compass (>= 1.0.0, < 2.0.0)
|
||||
@ -113,6 +115,10 @@ GEM
|
||||
tilt (~> 1.4.1)
|
||||
padrino-support (0.12.5)
|
||||
activesupport (>= 3.1)
|
||||
pry (0.10.3)
|
||||
coderay (~> 1.1.0)
|
||||
method_source (~> 0.8.1)
|
||||
slop (~> 3.4)
|
||||
rack (1.6.4)
|
||||
rack-livereload (0.3.16)
|
||||
rack
|
||||
@ -125,6 +131,7 @@ GEM
|
||||
redcarpet (3.3.3)
|
||||
rouge (1.10.1)
|
||||
sass (3.4.19)
|
||||
slop (3.6.0)
|
||||
sprockets (2.12.4)
|
||||
hike (~> 1.2)
|
||||
multi_json (~> 1.0)
|
||||
@ -159,7 +166,8 @@ DEPENDENCIES
|
||||
middleman-livereload
|
||||
middleman-minify-html
|
||||
middleman-syntax
|
||||
pry
|
||||
redcarpet
|
||||
|
||||
BUNDLED WITH
|
||||
1.10.6
|
||||
1.12.0.rc
|
||||
|
||||
22
config.rb
22
config.rb
@ -3,12 +3,32 @@
|
||||
# --------------------------------------
|
||||
|
||||
# ----- Site ----- #
|
||||
$last_version = "0.3.0"
|
||||
$languages = {
|
||||
de: "Deutsch",
|
||||
en: "English",
|
||||
"es-ES" => "Español",
|
||||
"pt-BR" => "Brazilian Portugese",
|
||||
ru: "Pyccкий",
|
||||
"zh-CN" => "简体中文",
|
||||
"zh-TW" => " 繁體中文"
|
||||
}
|
||||
|
||||
activate :i18n,
|
||||
lang_map: $languages,
|
||||
mount_at_root: :en
|
||||
|
||||
activate :i18n, langs: [:en, 'es-ES', 'pt-BR', :ru, 'zh-CN', 'zh-TW'], :mount_at_root => :en
|
||||
set :gauges_id, ''
|
||||
set :publisher_url, 'https://www.facebook.com/olivier.lacan.5'
|
||||
set :site_url, 'http://keepachangelog.com'
|
||||
|
||||
redirect "index.html", to: "en/#{$last_version}/index.html"
|
||||
|
||||
$languages.each do |language|
|
||||
language_param = language.last.parameterize
|
||||
redirect "#{language.first}/index.html", to: "#{language.first}/#{$last_version}/index.html"
|
||||
end
|
||||
|
||||
# ----- Assets ----- #
|
||||
|
||||
set :css_dir, 'assets/stylesheets'
|
||||
|
||||
@ -2,6 +2,7 @@
|
||||
description: Keep a Changelog
|
||||
title: Keep a Changelog
|
||||
language: de
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
:markdown
|
||||
@ -9,15 +10,17 @@ language: de
|
||||
|
||||
## Lass deine Freunde nicht CHANGELOGs mit git logs füllen™
|
||||
|
||||
Version **#{current_page.metadata[:page]["version"]}**
|
||||
|
||||
### Was ist ein Changelog?
|
||||
Ein Changelog ist eine Datei, welche eine nachgeführte, chronologisch sortierte
|
||||
Liste aller relevanten Änderungen für jede Version eines Projektes enthält.
|
||||
|
||||
%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__))
|
||||
%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md"))
|
||||
|
||||
:markdown
|
||||
### Was ist der Zweck eines Changelogs?
|
||||
Es für Benutzer und Entwickler einfacher zu machen, die relevanten Änderungen, welche
|
||||
Es für Benutzer und Entwickler einfacher zu machen, die relevanten Änderungen, welche
|
||||
zwischen Releases (oder Versionen) des Projekts gemacht wurden, zu sehen.
|
||||
|
||||
### Warum sollte ich mich darum kümmern?
|
||||
@ -84,7 +87,7 @@ language: de
|
||||
Es ist sicher nichts falsch daran, naiv zu zu sein, aber beim Verfassen eines Leitfadens
|
||||
ist es nicht wirklich hilfreich. Vor allem nicht, wenn es viele Spezialfälle zu beachten gibt.
|
||||
|
||||
Dieses Projekt [enthält das, wovon ich hoffe, dass es zu einer besseren CHANGELOG-Datei-Konvention][CHANGELOG]
|
||||
Dieses Projekt [enthält das, wovon ich hoffe, dass es zu einer besseren CHANGELOG-Datei-Konvention][CHANGELOG]
|
||||
wird. Ich glaube nicht, dass der status quo gut genug ist, und ich denke, dass wir als Community
|
||||
eine bessere Konvention entwickeln können, wenn wir Bewährtes aus echten
|
||||
Software-Projekten entnehmen. Schau dich um und denk daran, dass
|
||||
@ -101,8 +104,8 @@ language: de
|
||||
|
||||
### Wieso sollte man nicht einfach ein `git log` Diff verwenden?
|
||||
Weil log Diffs voller unnötiger Information sind - von Natur aus. Sie wären nicht
|
||||
einmal ein geeignetes Changelog in einem hypothetischen Projekt, welches von perfekten
|
||||
Menschen geführt wird, welche sich niemals vertippen, niemals vergessen, neue Dateien
|
||||
einmal ein geeignetes Changelog in einem hypothetischen Projekt, welches von perfekten
|
||||
Menschen geführt wird, welche sich niemals vertippen, niemals vergessen, neue Dateien
|
||||
zu comitten und nie einen Teil eines Refactorings übersehen.
|
||||
Der Zweck eines Commits ist es, einen atomaren Schritt eines Prozesses zu dokumentieren,
|
||||
welcher den Code von einem Zustand in den nächsten bringt. Der Zweck eines Changelogs
|
||||
@ -127,7 +130,7 @@ language: de
|
||||
|
||||
Die Grossschreibung (welche in alten Betriebssystemen dafür gesorgt hat,
|
||||
dass die Dateien zuerst aufgelistet wurden) wird verwendet, um die Aufmerksamkeit
|
||||
auf diese Dateien zu lenken. Da sie wichtige Metadaten über das Projekt enthalten,
|
||||
auf diese Dateien zu lenken. Da sie wichtige Metadaten über das Projekt enthalten,
|
||||
können sie wichtig für jeden sein, der das Projekt gerne benutzen oder mitentwickeln
|
||||
möchte, ähnlich wie [Open-Source-Projekt-Badges][shields].
|
||||
|
||||
184
source/en/0.3.0/index.haml
Normal file
184
source/en/0.3.0/index.haml
Normal file
@ -0,0 +1,184 @@
|
||||
---
|
||||
description: Keep a Changelog
|
||||
title: Keep a Changelog
|
||||
language: en
|
||||
version: 0.3.0
|
||||
redirect_path: /about/
|
||||
---
|
||||
|
||||
:markdown
|
||||
# Keep a CHANGELOG
|
||||
|
||||
## Don’t let your friends dump git logs into CHANGELOGs™
|
||||
|
||||
Version **#{current_page.metadata[:page]["version"]}**
|
||||
|
||||
### What’s a change log?
|
||||
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(File.join(root_path, "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.
|
||||
|
||||
### Why should I care?
|
||||
Because software tools are for people. If you don’t care, why are
|
||||
you contributing to open source? Surely, there must be a kernel (ha!)
|
||||
of care somewhere in that lovely little brain of yours.
|
||||
|
||||
I [talked with Adam Stacoviak and Jerod Santo on The Changelog][thechangelog]
|
||||
(fitting, right?) podcast about why maintainers and
|
||||
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?
|
||||
I’m glad you asked.
|
||||
|
||||
A good change log 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).
|
||||
- One sub-section per version.
|
||||
- List releases in reverse-chronological order (newest on top).
|
||||
- Write all dates in `YYYY-MM-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) It’s international, [sensible](http://xkcd.com/1179/), and language-independent.
|
||||
- Explicitly mention whether the project follows [Semantic Versioning][semver].
|
||||
- Each version should:
|
||||
- List its release date in the above format.
|
||||
- Group changes to describe their impact on the project, as follows:
|
||||
- `Added` for new features.
|
||||
- `Changed` for changes in existing functionality.
|
||||
- `Deprecated` for once-stable features removed in upcoming releases.
|
||||
- `Removed` for deprecated features removed in this release.
|
||||
- `Fixed` for any bug fixes.
|
||||
- `Security` to invite users to upgrade in case of vulnerabilities.
|
||||
|
||||
### How can I minimize the effort required?
|
||||
Always have an `"Unreleased"` section at the top for keeping track of any
|
||||
changes.
|
||||
|
||||
This serves two purposes:
|
||||
|
||||
- People can see what changes they might expect in upcoming releases
|
||||
- At release time, you just have to change `"Unreleased"` to the version number
|
||||
and add a new `"Unreleased"` header at the top.
|
||||
|
||||
### What makes unicorns cry?
|
||||
Alright…let’s get into it.
|
||||
|
||||
- **Dumping a diff of commit logs.** Just don’t do that, you’re helping nobody.
|
||||
- **Not emphasizing deprecations.** When people upgrade from one version to
|
||||
another, it should be painfully clear when something will break.
|
||||
- **Dates in region-specific formats.** In the U.S., people put the month first
|
||||
("06-02-2012" for June 2nd, 2012, which makes *no* sense), while many people
|
||||
in the rest of the world write a robotic-looking "2 June 2012", yet pronounce
|
||||
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.
|
||||
|
||||
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?
|
||||
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
|
||||
"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
|
||||
situations and edge cases to deal with.
|
||||
|
||||
This project [contains what I hope will become a better CHANGELOG file convention][CHANGELOG].
|
||||
I don't think the status quo is good enough, and I think that as a community we
|
||||
can come up with better conventions if we try to extract good practices from
|
||||
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?
|
||||
Well, if you can’t tell from the example above, `CHANGELOG.md` is the
|
||||
best convention so far.
|
||||
|
||||
Some projects also use `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
|
||||
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc.
|
||||
|
||||
It’s a mess. All these names only makes it harder for people to find it.
|
||||
|
||||
### 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
|
||||
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
|
||||
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:
|
||||
one describes the *why*, the other the how.
|
||||
|
||||
### Can change logs 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.
|
||||
|
||||
### Why do you alternate between spelling it "CHANGELOG" and "change log"?
|
||||
"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],
|
||||
and [`CONTRIBUTING`][CONTRIBUTING].
|
||||
|
||||
The uppercase naming (which in old operating systems made these files stick
|
||||
to the top) is used to draw attention to them. Since they're important
|
||||
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
|
||||
file: to log changes.
|
||||
|
||||
### What about yanked releases?
|
||||
Yanked releases are versions that had to be pulled because of a serious
|
||||
bug or security issue. Often these versions don't even appear in change
|
||||
logs. They should. This is how you should display them:
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [YANKED]`
|
||||
|
||||
The `[YANKED]` tag is loud for a reason. It's important for people to
|
||||
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
|
||||
pull requests to add missing releases to open source projects with unmaintained
|
||||
change logs.
|
||||
|
||||
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.
|
||||
|
||||
### How can I contribute?
|
||||
This document is not the **truth**; it’s my carefully considered
|
||||
opinion, along with information and examples I gathered.
|
||||
Although I provide an actual [CHANGELOG][] on [the GitHub repo][gh],
|
||||
I have purposefully not created a proper *release* or clear list of rules
|
||||
to follow (as [SemVer.org][semver] does, for instance).
|
||||
|
||||
This is because I want our community to reach a consensus. I believe the
|
||||
discussion is as important as the end result.
|
||||
|
||||
So please [**pitch in**][gh].
|
||||
|
||||
[CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
|
||||
[CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md
|
||||
[LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE
|
||||
[README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md
|
||||
[gemnasium]: https://gemnasium.com/
|
||||
[gh]: https://github.com/olivierlacan/keep-a-changelog
|
||||
[issues]: https://github.com/olivierlacan/keep-a-changelog/issues
|
||||
[semver]: http://semver.org/
|
||||
[shields]: http://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
@ -2,6 +2,7 @@
|
||||
description: Mantenga un Changelog
|
||||
title: Mantenga un Changelog
|
||||
language: es-ES
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
:markdown
|
||||
@ -9,11 +10,13 @@ language: es-ES
|
||||
|
||||
## No dejes que tus amigos copien y peguen git logs en los CHANGELOGs™
|
||||
|
||||
Version **#{current_page.metadata[:page]["version"]}**
|
||||
|
||||
### Qué es un registro de cambios (change log)?
|
||||
|
||||
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(File.expand_path("../../../CHANGELOG.md", __FILE__))
|
||||
%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md"))
|
||||
|
||||
:markdown
|
||||
### Cuál es el propósito del change log?
|
||||
@ -69,12 +72,12 @@ language: es-ES
|
||||
Pero espera! hay más ayúdame a coleccionar esas lágrimas de unicornio [abriendo una incidencia][issues] o haciendo un pull request.
|
||||
|
||||
### Hay algún formato estándar de formato para los change log?
|
||||
|
||||
|
||||
Tristemente, no. Pero calma. Sé que estás corriendo furiosamente intentando encontrar ese link al libro de estilo de registro de cambios de GNU, or the two-paragraph GNU NEWS file
|
||||
"guideline". La guía de estilo GNU es un buen comienzo, pero es tristemente cándida. No hay nada malo en ser cándida, pero cuando la gente necesita orientación es rara la vez, que resulta ser muy útil. Sobre todo, cuando hay muchas situaciones y casos muy específicos.
|
||||
|
||||
Este proyecto [contiene lo que espero se convierta en un mejor patrón de CHANGELOGs][CHANGELOG].
|
||||
|
||||
|
||||
No creo que la situación actual sea lo suficientemente buena, i creo que como comunidad que somos podemos llegar a mejores convenciones si tratamos de extraer buenas prácticas de proyectos de software reales. Por favor echa un pequeño vistazo y recuerda que las [sugerencias y discusiones para mejorar son bienvenidas][issues]!
|
||||
|
||||
### Cómo se debería llamar el change log?
|
||||
@ -89,7 +92,7 @@ language: es-ES
|
||||
### Por qué la gente no usa simplemente un `git log`?
|
||||
|
||||
Debido a que están llenos de ruido - por naturaleza. No se podría hacer un change log adecuado ni siquiera en un proyecto hipotético dirigido por seres humanos perfectos que nunca se equivocan y que nunca se olvidan meter ningún archivo en un commit... etc. El propósito de un commit es el de documentar un cambio atómico en el cual el software evoluciona desde un estado hacia otro. El propósito del change log es el de documentar las diferencias notables entre estos estados.
|
||||
|
||||
|
||||
### Se pueden parsear automáticamente los change logs?
|
||||
|
||||
Es difícil, ya que la gente sigue formatos y nombres de archivo muy distintos.
|
||||
@ -108,7 +111,7 @@ language: es-ES
|
||||
### Qué son las yanked releases?
|
||||
|
||||
Las yanked releases son versiones que tuvieron que ser retiradas a causa de un grave error o problema de seguridad. A menudo, estas versiones ni siquiera aparecen en los change logs, y tendrían que aparecer. Así es como se muestran:
|
||||
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [YANKED]`
|
||||
|
||||
La sección `[YANKED]` va entre corchetes por una razón, es importante que destaque, y el echo de estar rodeado por corchetes lo hace más fácil de localizar programáticamente.
|
||||
@ -2,6 +2,7 @@
|
||||
description: Keep a Changelog
|
||||
title: Keep a Changelog
|
||||
language: en
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
:markdown
|
||||
@ -9,11 +10,13 @@ language: en
|
||||
|
||||
## Don’t let your friends dump git logs into CHANGELOGs™
|
||||
|
||||
Version **#{current_page.metadata[:page]["version"]}**
|
||||
|
||||
### What’s a change log?
|
||||
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(File.expand_path("../../CHANGELOG.md", __FILE__))
|
||||
%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md"))
|
||||
|
||||
:markdown
|
||||
### What’s the point of a change log?
|
||||
|
||||
@ -31,13 +31,9 @@
|
||||
%header{role: "banner"}
|
||||
%nav.locales{role: "navigation"}
|
||||
%ul
|
||||
%li= link_to 'english [en]', '/', {rel: "alternate", lang: "en", hreflang: "en"}
|
||||
%li= link_to 'español [es-ES]', '/es-ES/', {rel: "alternate", lang: "es-ES", hreflang: "es-ES"}
|
||||
%li= link_to 'português brasileiro [pt-BR]', '/pt-BR/', {rel: "alternate", lang: "pt-BR", hreflang: "pt-BR"}
|
||||
%li= link_to 'pyccкий [ru]', '/ru/', {rel: "alternate", lang: "ru", hreflang: "ru"}
|
||||
%li= link_to '简体中文 [zh-CN]', '/zh-CN/', {rel: "alternate", lang: "zh-CN", hreflang: "zh-CN"}
|
||||
%li= link_to '繁體中文 [zh-TW]', '/zh-TW/', {rel: "alternate", lang: "zh-TW", hreflang: "zh-TW"}
|
||||
%li= link_to 'german [de]', '/de/', {rel: "alternate", lang: "de", hreflang: "de"}
|
||||
- $languages.each do |language|
|
||||
%li= link_to "#{language.last} [#{language.first}]", "/#{language.first}/",
|
||||
{ rel: "alternate", lang: "#{language}", hreflang: "#{language}" }
|
||||
|
||||
.main{role: "main"}= yield
|
||||
|
||||
|
||||
@ -2,6 +2,7 @@
|
||||
description: Mantenha um CHANGELOG
|
||||
title: Mantenha um CHANGELOG
|
||||
language: pt-BR
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
:markdown
|
||||
@ -9,13 +10,15 @@ language: pt-BR
|
||||
|
||||
## Não deixe seus amigos despejar logs de commits em CHANGELOGs™
|
||||
|
||||
Version **#{current_page.metadata[:page]["version"]}**
|
||||
|
||||
### O que é um change log?
|
||||
|
||||
Um *change log* é um arquivo que contém uma lista selecionada, ordenada
|
||||
cronologicamente de mudanças significativas para cada versão de um projeto
|
||||
open source.
|
||||
|
||||
%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__))
|
||||
%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md"))
|
||||
|
||||
:markdown
|
||||
### Para que serve um *change log*?
|
||||
@ -2,6 +2,7 @@
|
||||
description: Ведите Changelog
|
||||
title: Ведите Changelog
|
||||
language: ru
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
:markdown
|
||||
@ -9,13 +10,15 @@ language: ru
|
||||
|
||||
## Не позволяйте друзьям сливать логи гита в CHANGELOG™
|
||||
|
||||
Version **#{current_page.metadata[:page]["version"]}**
|
||||
|
||||
### Что такое лог изменений?
|
||||
|
||||
Лог изменений – это файл, который содержит поддерживаемый, упорядоченный в
|
||||
хронологическом порядке список значимых изменений для каждой версии проекта с
|
||||
открытым исходным кодом.
|
||||
|
||||
%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__))
|
||||
%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md"))
|
||||
|
||||
:markdown
|
||||
### Для чего нужен лог изменений?
|
||||
@ -92,7 +95,7 @@ language: ru
|
||||
[стандартом ISO](http://www.iso.org/iso/home/standards/iso8601.htm). Таким
|
||||
образом, этот формат является рекомендуемым для логов изменений.
|
||||
|
||||
Существуют и другие. Помогите мне собрать слёзы единорогов,
|
||||
Существуют и другие. Помогите мне собрать слёзы единорогов,
|
||||
[открыв тикет][issues] или пулл-реквест.
|
||||
|
||||
### Существует стандарт формата лога изменений?
|
||||
@ -2,6 +2,7 @@
|
||||
description: 如何维护更新日志
|
||||
title: 如何维护更新日志
|
||||
language: zh-CN
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
:markdown
|
||||
@ -9,21 +10,23 @@ language: zh-CN
|
||||
|
||||
## 更新日志绝对不应该是git日志的堆砌物
|
||||
|
||||
Version **#{current_page.metadata[:page]["version"]}**
|
||||
|
||||
### 更新日志是什么？
|
||||
更新日志（Change Log）是一个由人工编辑，以时间为倒叙的列表。
|
||||
这个列表记录所有版本的重大变动。
|
||||
|
||||
|
||||
%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__))
|
||||
%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md"))
|
||||
|
||||
:markdown
|
||||
### 为何要提供更新日志？
|
||||
为了让用户和开发人员更好知道每一个版本有哪些区别。
|
||||
|
||||
|
||||
### 为何我要在乎呢？
|
||||
因为归根结底软件是为人提供的。既然你不关心人，哪么为何写软件呢？
|
||||
多少你还是要关心你的受众。
|
||||
|
||||
|
||||
本文档原作者和另外两个人的一个[播客][thechangelog]向大家介绍了，
|
||||
为何代码的管理者和开发者应该在乎更新日志。如果你有一小时时间和很好的英文听力本领，
|
||||
不放听听。
|
||||
@ -32,7 +35,7 @@ language: zh-CN
|
||||
好问题！
|
||||
|
||||
一个好的更新日志，一定满足：
|
||||
|
||||
|
||||
- 给人而不是机器写的。记住，要说人话。
|
||||
- 快速跳转到任意段。所以采用markdown格式
|
||||
- 一个版本对应一个章节。
|
||||
@ -49,88 +52,88 @@ language: zh-CN
|
||||
- 'Removed' 之前不建议使用的功能，这次真的删掉了
|
||||
- 'Fixed' 改的bug
|
||||
- 'Security' 改的有关安全相关bug
|
||||
|
||||
|
||||
|
||||
|
||||
### 怎么尽可能减少耗费的精力？
|
||||
永远在文档最上方提供一个'Unreleased' 未发布区域，来记录当前的变化。
|
||||
这佯作有两大意义。
|
||||
|
||||
|
||||
- 大家可以看到接下来会有什么变化
|
||||
- 在发布时，只要把'Unreleased'改为当前版本号，然后再添加一个新的'Unreleased'就行了
|
||||
|
||||
|
||||
|
||||
### 吐槽环节到了
|
||||
请你一定要注意：
|
||||
|
||||
|
||||
- **把git日志扔到更新日志里。**看似有用，然并卵。
|
||||
- **不写'deprecations'就删功能。**不带这样坑队友的。
|
||||
- **采用各种不靠谱日期格式** 2012年12月12日，也就中国人能看懂了。
|
||||
|
||||
|
||||
如果你还有要吐槽的，欢迎留[issue][issues]或者直接PR
|
||||
|
||||
|
||||
|
||||
### 世界上不是有标准的更新日志格式吗？
|
||||
貌似GNU或者GNU NEWS还是提过些规范的，事实是它们太过简陋了。
|
||||
开发有那么多中情况，采用那样的规范，确实是不太合适的。
|
||||
|
||||
|
||||
这个项目提供的[规范][CHANGELOG]是作者本人希望能够成为世界规范的。
|
||||
作者不认为当前的标准足够好，而且作为一个社区，我们是有能力提供更棒的规范。
|
||||
如果你对这个规范有不满的地方，不要忘记还可以[吐槽][issues]呢。
|
||||
|
||||
|
||||
### 更新日志文件名应该叫什么？
|
||||
|
||||
我们的案例中给的名字就是最好的规范：`CHANGELOG.md`，注意大小写。
|
||||
|
||||
|
||||
像`HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
|
||||
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`这么
|
||||
多文件名就太不统一了。
|
||||
|
||||
|
||||
只会让大家更难找到。
|
||||
|
||||
|
||||
### 为何不直接记录`git log`?
|
||||
|
||||
因为git日志一定是乱糟糟的。哪怕一个最理想的由完美的程序员开发的提交的，哪怕一个
|
||||
从不忘记每次提交全部文件，不写错别字，不忘记重构每一个部分——也无法保证git日志完美无瑕。
|
||||
况且git日志的核心在于记录代码的演化，而更新日志则是记录最重要的变更。
|
||||
|
||||
|
||||
就像注释之于代码，更新日志之于git日志。前者解释*为什么*，而后者说明*发生了什么*。
|
||||
|
||||
|
||||
### 更新日志能机器识别吗？
|
||||
非常困难，因为有各种不同的文件格式和其他规范。
|
||||
|
||||
|
||||
[Vandamme][vandamme]是一个Ruby程序（由[Gemnasium][gemnasium]团队制作），可以解析
|
||||
好多种（但绝对不是全部）开源库的更新日志。
|
||||
|
||||
|
||||
### 到底是CHANGELOG还是更新日志
|
||||
|
||||
|
||||
CHANGELOG是文件名，更新日志是常用说法。CHANGELOG采用大写是有历史根源的。就像很多类似的文件
|
||||
[`README`][README]， [`LICENSE`][LICENSE]，还有[`CONTRIBUTING`][CONTRIBUTING]。
|
||||
|
||||
|
||||
采用大写可以更加显著，毕竟这是项目很重要的元信息。就像[开源徽章][shields]。
|
||||
|
||||
|
||||
### 那些后来撤下的版本怎么办？
|
||||
因为各种安全/重大bug原因被撤下的版本被标记'YANKED'。这些版本一般不出现在更新日志里，但作者建议他们出现。
|
||||
显示方式应该是：
|
||||
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [YANKED]`
|
||||
|
||||
|
||||
`[YANKED]`采用大写更加显著，因为这个信息很重要。而采用方括号则容易被程序解析。
|
||||
|
||||
|
||||
### 是否可以重写更新日志
|
||||
当然。哪怕已经上线了，也可以重新更新更新日志。有许多开源项目更新日志不够新，所以作者就会帮忙更新。
|
||||
|
||||
|
||||
另外，很有可能你忘记记录一个重大功能更新。所以这时候应该去重写更新日志。
|
||||
|
||||
|
||||
### 如何贡献？
|
||||
本文档并不是**真理**。这只是原作者的个人建议，并且包括许多收集的例子。
|
||||
哪怕[本开源库][gh]提供一个[更新日志案例][CHANGELOG]，我刻意没有提供一个
|
||||
过于苛刻的规则列表（不像[语义化版本格式][semver]）。
|
||||
|
||||
|
||||
这是因为我希望通过社区达到统一观点，我认为中间讨论的过程与结果一样重要。
|
||||
|
||||
|
||||
所以[欢迎贡献][gh]。
|
||||
|
||||
|
||||
|
||||
[CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
|
||||
[CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md
|
||||
@ -2,6 +2,7 @@
|
||||
description: 如何維護更新日誌
|
||||
title: 如何維護更新日誌
|
||||
language: zh-TW
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
:markdown
|
||||
@ -9,21 +10,23 @@ language: zh-TW
|
||||
|
||||
## 更新日誌絕對不應該是git日誌的堆砌物
|
||||
|
||||
Version **#{current_page.metadata[:page]["version"]}**
|
||||
|
||||
### 更新日誌是什麽？
|
||||
更新日誌（Change Log）是壹個由人工編輯，以時間為倒敘的列表。
|
||||
這個列表記錄所有版本的重大變動。
|
||||
|
||||
|
||||
%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__))
|
||||
%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md"))
|
||||
|
||||
:markdown
|
||||
### 為何要提供更新日誌？
|
||||
為了讓用戶和開發人員更好知道每壹個版本有哪些區別。
|
||||
|
||||
|
||||
### 為何我要在乎呢？
|
||||
因為歸根結底軟件是為人提供的。既然妳不關心人，哪麽為何寫軟件呢？
|
||||
多少妳還是要關心妳的受眾。
|
||||
|
||||
|
||||
本文檔原作者和另外兩個人的壹個[播客][thechangelog]向大家介紹了，
|
||||
為何代碼的管理者和開發者應該在乎更新日誌。如果妳有壹小時時間和很好的英文聽力本領，
|
||||
不放聽聽。
|
||||
@ -32,7 +35,7 @@ language: zh-TW
|
||||
好問題！
|
||||
|
||||
壹個好的更新日誌，壹定滿足：
|
||||
|
||||
|
||||
- 給人而不是機器寫的。記住，要說人話。
|
||||
- 快速跳轉到任意段。所以采用markdown格式
|
||||
- 壹個版本對應壹個章節。
|
||||
@ -49,88 +52,88 @@ language: zh-TW
|
||||
- 'Removed' 之前不建議使用的功能，這次真的刪掉了
|
||||
- 'Fixed' 改的bug
|
||||
- 'Security' 改的有關安全相關bug
|
||||
|
||||
|
||||
|
||||
|
||||
### 怎麽盡可能減少耗費的精力？
|
||||
永遠在文檔最上方提供壹個'Unreleased' 未發布區域，來記錄當前的變化。
|
||||
這佯作有兩大意義。
|
||||
|
||||
|
||||
- 大家可以看到接下來會有什麽變化
|
||||
- 在發布時，只要把'Unreleased'改為當前版本號，然後再添加壹個新的'Unreleased'就行了
|
||||
|
||||
|
||||
|
||||
### 吐槽環節到了
|
||||
請妳壹定要註意：
|
||||
|
||||
|
||||
- **把git日誌扔到更新日誌裏。**看似有用，然並卵。
|
||||
- **不寫'deprecations'就刪功能。**不帶這樣坑隊友的。
|
||||
- **采用各種不靠譜日期格式** 2012年12月12日，也就中國人能看懂了。
|
||||
|
||||
|
||||
如果妳還有要吐槽的，歡迎留[issue][issues]或者直接PR
|
||||
|
||||
|
||||
|
||||
### 世界上不是有標準的更新日誌格式嗎？
|
||||
貌似GNU或者GNU NEWS還是提過些規範的，事實是它們太過簡陋了。
|
||||
開發有那麽多中情況，采用那樣的規範，確實是不太合適的。
|
||||
|
||||
|
||||
這個項目提供的[規範][CHANGELOG]是作者本人希望能夠成為世界規範的。
|
||||
作者不認為當前的標準足夠好，而且作為壹個社區，我們是有能力提供更棒的規範。
|
||||
如果妳對這個規範有不滿的地方，不要忘記還可以[吐槽][issues]呢。
|
||||
|
||||
|
||||
### 更新日誌文件名應該叫什麽？
|
||||
|
||||
我們的案例中給的名字就是最好的規範：`CHANGELOG.md`，註意大小寫。
|
||||
|
||||
|
||||
像`HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
|
||||
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`這麽
|
||||
多文件名就太不統壹了。
|
||||
|
||||
|
||||
只會讓大家更難找到。
|
||||
|
||||
|
||||
### 為何不直接記錄`git log`?
|
||||
|
||||
因為git日誌壹定是亂糟糟的。哪怕壹個最理想的由完美的程序員開發的提交的，哪怕壹個
|
||||
從不忘記每次提交全部文件，不寫錯別字，不忘記重構每壹個部分——也無法保證git日誌完美無瑕。
|
||||
況且git日誌的核心在於記錄代碼的演化，而更新日誌則是記錄最重要的變更。
|
||||
|
||||
|
||||
就像註釋之於代碼，更新日誌之於git日誌。前者解釋*為什麽*，而後者說明*發生了什麽*。
|
||||
|
||||
|
||||
### 更新日誌能機器識別嗎？
|
||||
非常困難，因為有各種不同的文件格式和其他規範。
|
||||
|
||||
|
||||
[Vandamme][vandamme]是壹個Ruby程序（由[Gemnasium][gemnasium]團隊制作），可以解析
|
||||
好多種（但絕對不是全部）開源庫的更新日誌。
|
||||
|
||||
|
||||
### 到底是CHANGELOG還是更新日誌
|
||||
|
||||
|
||||
CHANGELOG是文件名，更新日誌是常用說法。CHANGELOG采用大寫是有歷史根源的。就像很多類似的文件
|
||||
[`README`][README]， [`LICENSE`][LICENSE]，還有[`CONTRIBUTING`][CONTRIBUTING]。
|
||||
|
||||
|
||||
采用大寫可以更加顯著，畢竟這是項目很重要的元信息。就像[開源徽章][shields]。
|
||||
|
||||
|
||||
### 那些後來撤下的版本怎麽辦？
|
||||
因為各種安全/重大bug原因被撤下的版本被標記'YANKED'。這些版本壹般不出現在更新日誌裏，但作者建議他們出現。
|
||||
顯示方式應該是：
|
||||
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [YANKED]`
|
||||
|
||||
|
||||
`[YANKED]`采用大寫更加顯著，因為這個信息很重要。而采用方括號則容易被程序解析。
|
||||
|
||||
|
||||
### 是否可以重寫更新日誌
|
||||
當然。哪怕已經上線了，也可以重新更新更新日誌。有許多開源項目更新日誌不夠新，所以作者就會幫忙更新。
|
||||
|
||||
|
||||
另外，很有可能妳忘記記錄壹個重大功能更新。所以這時候應該去重寫更新日誌。
|
||||
|
||||
|
||||
### 如何貢獻？
|
||||
本文檔並不是**真理**。這只是原作者的個人建議，並且包括許多收集的例子。
|
||||
哪怕[本開源庫][gh]提供壹個[更新日誌案例][CHANGELOG]，我刻意沒有提供壹個
|
||||
過於苛刻的規則列表（不像[語義化版本格式][semver]）。
|
||||
|
||||
|
||||
這是因為我希望通過社區達到統壹觀點，我認為中間討論的過程與結果壹樣重要。
|
||||
|
||||
|
||||
所以[歡迎貢獻][gh]。
|
||||
|
||||
|
||||
|
||||
[CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
|
||||
[CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md
|
||||
Loading…
x
Reference in New Issue
Block a user