tyler.durden/keep-a-changelog
1
0
Fork 0
mirror of https://github.com/olivierlacan/keep-a-changelog.git synced 2025-07-29 16:54:12 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'olivierlacan/master'

Browse Source
This commit is contained in:
Emre Erkan 2017-03-20 14:28:56 +03:00
commit 30ad8655cf
12 changed files with 896 additions and 122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
CHANGELOG.md
View File

@ -1,17 +1,23 @@
# Change Log
All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).
The format is based on [Keep a Changelog](http://keepachangelog.com/)
and this project adheres to [Semantic Versioning](http://semver.org/).
## [Unreleased]
### Added
- zh-CN and zh-TW translations from @tianshuo.
- de translation from @mpbzh.
- it-IT translation from @roalz.
- sv translation from @magol.
- tr-TR translation from @karalamalar.
- fr translation from @zapashcanon.
### Changed
- Start versioning based on the current English version at 0.3.0 to help
translation authors keep things up-to-date.
- Fix typos in zh-CN translation.
- Fix typos in pt-BR translation.
## [0.3.0] - 2015-12-03
### Added

14
config.rb
View File

@ -5,15 +5,19 @@
# ----- Site ----- #
$last_version = "0.3.0"
$languages = {
"cs" => "Čeština",
"de" => "Deutsch",
"en" => "English",
"es-ES" => "Español",
"fr" => "Français",
"it-IT" => "Italiano",
"pt-BR" => "Brazilian Portugese",
"ru" => "Pyccкий",
"sl" => "Slovenščina",
"sv" => "Svenska",
"tr-TR" => "Türkçe",
"zh-CN" => "简体中文",
"zh-TW" => " 繁體中文",
de: "Deutsch",
en: "English",
ru: "Pyccкий",
"tr-TR" => "Türkçe"
"zh-TW" => " 繁體中文"
}
activate :i18n,

177
source/cs/0.3.0/index.html.haml Normal file
View File

@ -0,0 +1,177 @@
---
description: Udržuj Changelog
title: Udržuj Changelog
language: cs
version: 0.3.0
---
:markdown
# Udržuj CHANGELOG
## Nenech své kamarády házet do CHANGELOGů™ git logy.
Version **#{current_page.metadata[:page][:version]}**
### Co je to changelog?
Changelog je soubor, který obsahuje organizovaný, chronologicky seřazený
seznam podstatných změn pro každou verzi daného projektu.
%pre.changelog= File.read("CHANGELOG.md")
:markdown
### Co je smyslem changelogu?
Usnadnit uživatelům a přispěvatelům přesné zobrazení podstatných změn, které
byly provedeny mezi jednotlivými vydáními (verzemi) daného projektu.
### Proč by mi na tom mělo záležet?
Protože softwarové nástroje jsou pro lidi. Pokud ti na tom nezáleží, tak proč
přispíváš do open source projektů? Určitě musí být v tvém úžasném malém mozku
alespoň jádro (haha!) ochoty.
[Bavil jsem se s Adamem Stacoviakem a Jerodem Santem na podcastu The Changelog][thechangelog]
(název sedí, co?) o tom proč by na tom mělo vedoucím a přispěvatelům projektů
záležet a o tom jaká motivace je za tímto projektem. Jestli máš chvilku času
(1:06), stojí to za poslech.
### Co dělá changelog dobrým?
Výborná otázka, díky za ni.
Dobrý changelog se drří těchto principů:
- Je psaný pro lidi, ne pro stroje, takže čitelnost je zásadní.
- Dá se v něm jednoduše odkázat na libovolnou sekci (proto raději Markdown než plain text).
- Jedna pod-sekce za verzi.
- Seznam vydání ve zpětně-chronologickém pořadí (nejnovější navrchu).
- Psaní všech dat ve formátu `RRRR-MM-DD`. (Příklad: `2012-06-02` pro `2. červen 2012`.) Je to mezinárodní, [rozumné](http://xkcd.com/1179/) a nezávislé na jazyce.
- Explicitní uvedení toho, zda projekt dodržuje [Semantické Verzování][semver].
- Každá verze by měla:
- Uvádět datum vydání ve výše uvedeném formátu.
- Seskupovat změny tak, aby popisovaly dopad na projekt, a to následovně:
- `Added` pro nové funkce.
- `Changed` pro změny v aktuálním fungování.
- `Deprecated` pro dříve stabilní funkce, které budou odstraněny v novějších vydáních a nejsou podporovány.
- `Removed` pro funkce odstraněné v daném vydání.
- `Fixed` pro opravené chyby.
- `Security` pro navržení aktualizace uživatelům v případě bezpečnostních problémů.
### Jak mohu vyžadovanou snahu snížit na minimum?
Vždycky měj nahoře sekci `"Unreleased"`, ve které budou schromažďovány všechny
změny.
To plní hned dva účely:
- Lidé uvidí, jaké změny mohou očekávat v následujících vydáních
- V momentu vydání stačí změnit `"Unreleased"` na číslo verze a přidat nový nadpis `"Unreleased"` na vrch dokumentu.
### Co zaručeně rozbrečí jednorožce?
Dobrá… Tak si to povíme.
- **Zkopírování diffu commit logů.** To prostě nedělej, nikomu to nepomůže.
- **Nezdůraznění dále nepodporovaných funcí.** Když lidé aktualizují na novou verzi, mělo by jim být bolestivě jasné, že se něco rozbije.
- **Data v regionálních formátech.** V USA píšou lidé nejdříve měsíc ("06-02-2012" pro 2. června 2012, což nedává *vůbec žádný* smysl), zatímco mnoho lidí ve zbytku světa píše roboticky vypadající verzi "2 June 2012", ale vyslovují to jinak. "2012-06-02" je logicky napsané od největšího po nejmenší celek, nepřekrývá se nesrozumitelně s jinými fomáty data a je to [ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Proto je to doporučovaný formát dat pro changelogy.
To ale není všechno. Pomoz mi sbírat jednorožčí slzy tím že
[otevřeš issue][issues] nebo pull request.
### Existuje pro formát changelogů nějaký standard?
Bohužel ne. Klid. Vím, že se zuřivě snažíš najít ten odkaz na GNU návod jakým
stylem psát changelog, nebo onen dvouodstavcový GNU NEWS soubor, který si říká
"směrnice". Zmíněný GNU návod je sice hezký začátek, ale je smutně naivní. Být
naivní není nic špatného, ale když lidé potřebují radu, málokdy to někomu
pomůže. Obzvlášť, když existuje tolik situací a okrajových případů, se kterými
se musí člověk nějak poprat.
Tento projekt
[obsahuje něco, co se doufám jednou stane lepší konvencí pro CHANGELOGy][CHANGELOG].
Nemyslím si, že je momentální stav dostatečně dobrý, a jsem toho názoru, že
jsme jako komunita schopni vymyslet lepší konvence, pokud se budeme snažit
vybrat ty nejlepší praktiky z doopravdových softwarových projektů.
Porozhlédněte se a mějte na paměti, že
[diskuse a návrhy na zlepšení jsou vítány][issues]!
### Jak by se měl changelog jmenovat?
Inu, pokud jste to už nepoznali z příkladu výše, `CHANGELOG.md` je zatím ta
nejlepší konvence.
Některé projekty používají `HISTORY.txt`, `HISTORY.md`, `History.md`,
`NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`,
`releases.md`, apod.
Je v tom binec. Všecha tato jména jen komplikují život lidem, kteří se ten
dokument snaží najít.
### Proč lidé jednoduše nepoužívají `git log` diff?
Protože diffy logů jsou plné šumu — přirozeně. Nebyly by vyhovujícím
changelogem ani v hypotetickém projektu vedeném dokonalými lidmi, kteří nikdy
nedělají překlepy, nikdy nezapomínají commitnout nové soubory a nikdy jim
neunikne ani ta nejmenší část refactoringu. Cílem commitu je dokumentovat
jeden miniaturní krok při procesu, ve kterém se kód vyvíjí z jedné podoby do
druhé. Cílem changelogu je dokumentovat podstatné změny mezi těmito podobami.
Stějně jako je rozdíl mezi dobrými komentáři a samotným kódem, je také rozdíl
mezi changelogem a commitlogem: jeden říká *proč* a druhý jak.
### Mohou být changelogy automaticky parsované?
Je to složité, jelikož se lidé uchylují k nejrůznějším formátům a názvům
souborů.
[Vandamme][vandamme] je Ruby gem vytvořený týmem [Gemnasium][gemnasium], který
parsuje mnoho (ale ne všechny) changelogů open source projektů.
### Proč používáš jednou "CHANGELOG" a jindy "changelog"?
"CHANGELOG" je název samotného souboru. Je to třichu křiklavé, ale to už je
historická konvence, kterou se řídí mnoho open source projektů. Příklady
podobných souborů mohou být [`README`][README], [`LICENSE`][LICENSE] a
[`CONTRIBUTING`][CONTRIBUTING].
Název psaný kapitálkami (díky kterému se ve starých operačních systémech
soubory držely na nejvyšších pozicích) je používán za účelem upoutání
pozornosti. Vzhledem k tomu, že se jedná o důležitá metadata o projektu a
mohla by být užitečná pro kohokoliv, kdo ho chce používat nebo do něho
přispívat, podobně [open source projektovým odznakům][shields].
Když mluvím o "changelogu", myslím tím funkci tohoto souboru: logování změn.
### Jak potom vypadají ta vydání, která byla zpětně stažena?
Zpětně stažená vydání jsou verze, které musely být zpětně odebrány kvůli vážné
chybě nebo bezpečnostním rizikům. Tyto verze se často v changelogu ani
neobjevují, ale měly by. Zobrazovat by se měli takto:
`## 0.0.5 - 2014-12-13 [YANKED]`
Tag `[YANKED]` je naschvál křiklavý. Je důležité, aby si ho lidé všimli. Díky
tomu, že je v hranatých závorkách je take jednoduší ho parsovat programem.
### Měl by se někdy changelog přepisovat?
Jasně. Vždy se najde dobrý důvod pro zlepšení changelogu. Sám často otevírám
pull requesty pro přidání chybějících vydání v open source projektech s
neudržovanými changelogy.
Je také možné, že zjistíš, že v poznámkách k verzi ve tvém projektu není
zmíněna změna, která něco mohla rozbít. V tom případě jě samozřejmě důležité,
aby byl changelog aktualizován.
### Jak mohu přidat ruku k dílu?
Tento dokument není čistá **pravda**; je to můj názor, nad kterým jsem opatrně
uvažoval, v kombinaci s informacemi a příklady, které se mi podařilo získat.
I přesto, že uvádím vlastní [CHANGELOG][] v [repozitáři na GitHubu][gh],
naschvál jsem nevytvořil náležité *vydání* nebo jasný seznam pravidel, kterými
se někdo má řídit (jako to například udělali na [SemVer.org][semver]).
Je tomu tak proto, že chci aby komunita došla ke společné shodě. Já sám jsem
toho názoru, že diskuse je důležitou součástí finálního výsledku.
Takže prosím [**přispějte**][gh] svou trochou do mlýna.
[CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
[CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md
[LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE
[README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md
[gemnasium]: https://gemnasium.com/
[gh]: https://github.com/olivierlacan/keep-a-changelog
[issues]: https://github.com/olivierlacan/keep-a-changelog/issues
[semver]: http://semver.org/
[shields]: http://shields.io/
[thechangelog]: http://5by5.tv/changelog/127
[vandamme]: https://github.com/tech-angels/vandamme/

35
source/de/0.3.0/index.html.haml
View File

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

210
source/fr/0.3.0/index.html.haml Normal file
View File

@ -0,0 +1,210 @@
---
description: Tenez un Changelog
title: Tenez un Changelog
language: fr
version: 0.3.0
---
:markdown
# Tenez un CHANGELOG
## Ne laissez pas vos amis utiliser les logs git comme CHANGELOGs™
Version **#{current_page.metadata[:page][:version]}**
### Qu’est-ce qu’un journal des modifications (change log) ?
Un journal des modifications (ou change log) est un fichier qui contient
une liste triée chronologiquement des changements notables pour chaque
version d’un projet
%pre.changelog= File.read("CHANGELOG.md")
:markdown
### Quel est l’intérêt d’un change log ?
Il permet aux utilisateurs et aux contributeurs de voir plus simplement
les changements notables qui ont été réalisés entre chaque publication
(ou version) du projet.
### Pourquoi devrais-je m’en préoccuper ?
Parce que les logiciels sont pour les gens. Si vous ne vous en souciez pas,
pourquoi contribuez-vous à l’open source ? Il doit sûrement y avoir un
"kernel" (ha!) d’intérêt pour ça quelque part dans votre cher petit
cerveau.
J’ai [discuté avec Adam Stacoviak et Jerod Santo dans le podcast
"The Changelog"][thechangelog] (approprié, non ?) des raisons pour
lesquelles les mainteneurs et les contributeurs devraient s’en préoccuper ;
également des motivations derrière ce projet.
Si vous avez le temps (1:06), l’écoute vaut le coup.
### Qu’est-ce qui fait un bon change log ?
Heureux de vous entendre le demander.
Un bon change log se conforme à ces principes:
- Il est fait pour des humains, pas des machines, la lisibilité est donc
cruciale.
- Facilité de faire un lien vers n’importe quelle section (d’où le Markdown
plutôt que le text brut).
- Une sous-section par version.
- Liste les publications dans l’ordre chronologique inverse (les plus récentes
en haut).
- Toutes les dates sont au format `AAAA-MM-JJ`. (Exemple: `2012-06-02` pour le
`2 Juin 2012`.) C’est international, [raisonnable](http://xkcd.com/1179/) et
indépendant de la langue.
- Mentionne explicitement si le projet respecte le
[Versionnage Sémantique][semver].
- Chaque version devrait:
- Lister sa date de publication au format ci-dessus.
- Regrouper les changements selon leur impact sur le projet, comme suit:
- `Added` pour les nouvelles fonctionnalités.
- `Changed` pour les changements au sein des fonctionnalités déjà
existantes.
- `Deprecated` pour les fonctionnalités qui seront supprimées dans la
prochaine publication.
- `Removed` pour les anciennes fonctionnalités `Deprecated` qui viennent
d’être supprimées.
- `Fixed` pour les corrections de bugs.
- `Security` pour encourager les utilisateurs à mettre à niveau afin
d’éviter des failles de sécurité.
### Comment puis-je minimiser le travail nécessaire ?
Ayez toujours une section `"Unreleased"` en haut du fichier afin de lister
tous les changements pas encore publiés.
Cela rempli deux objectifs:
- Les gens peuvent voir les changements auxquels ils peuvent s’attendrent dans
les prochaines publications
- Au moment de la publication, vous n’avez qu’à remplacer `"Unreleased"` par
la nouvelle version et rajouter une nouvelle section `"Unreleased"`
au-dessus.
### Quelles sont les choses qui rendent tristes les licornes ?
Très bien… parlons-en.
- **Recopier les dernier logs git.** Ne faites simplement pas cela, vous
n’aidez personne.
- **Ne pas mettre l’accent sur les fonctionnalités dépréciées.** Quand les
gens mettent à niveau d’une version vers une autre, le fait que quelque
chose ne soit pas compatible devrait être évident.
- **Les dates dans des formats spécifiques à une région.** Aux États-Unis, les
gens mettent le mois en premier ("06-02-2012" pour le 2 Juin 2012, ce qui
n’a *pas* de sens), tandis que beaucoup de gens dans le reste du monde
l’écrivent de la façon robotique suivante "2 Juin 2012", alors qu’ils le
prononcent différement. "2012-06-02" fonctionne logiquement, du plus grand
au plus petit, ne laisse pas place à la confusion avec un autre format et
est un [standard ISO](http://www.iso.org/iso/home/standards/iso8601.htm).
Voilà pourquoi il est le format de dates recommandé pour les change logs.
Il y en a d’autres. Aidez-moi à collecter ces larmes de licornes en
[ouvrant une issue][issues] ou une pull request.
### Y a-t-il un format de change log standard ?
Malheureusement, non. Du calme. Je sais que vous êtes en train de vous
précipiter afin de trouver le lien vers le guide pour change logs GNU, ou le
fichier GNU NEWS "guideline" de deux paragraphes. Le guide GNU est un bon
début mais il est malheureusement simpliste. Il n'y a rien de mal avec le fait
d'être simpliste, mais quand les gens ont besoin d'être guidés, ce n'est que
rarement utile. Spécialement quand il a beaucoup de situations et de cas
particuliers à prendre en compte.
Ce projet [contient ce que j'espère devenir une meilleur convention pour les fichiers CHANGELOG][CHANGELOG].
Je ne pense pas que le status quo soit suffisant et je pense qu'en tant que
communauté, nous pouvons arriver à de meilleures conventions si nous essayons
d'extraire les meilleures pratiques depuis les vrais projets logiciels. S'il
vous plaît, jetez-y un coup d'oeil et rappelez vous que les
[discussions et les suggestions d'améliorations sont les bienvenues][issues]!
### Comment doit-être nommé le fichier de change log ?
Eh bien, si l'exemple ci-dessus ne vous suffit pas à le deviner,
`CHANGELOG.md` est la meilleure convention à ce jour.
Certains projets utilisent aussi `HISTORY.txt`, `HISTORY.md`, `History.md`,
`NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`,
`releases.md`, etc.
C'est un véritable bazar. Tous ces noms ne font que rendre plus difficile son
repérage par les gens.
### Pourquoi les gens ne recopient pas simplement les derniers logs git ?
Parce que les logs gits sont remplis de bruit - par définition. Ils ne peuvent
pas faire office de change log convenable, même dans un hypothétique projet
tenu par des humains parfaits qui ne font jamais la moindre faute de frappe,
n'oublient jamais de committer les nouveaux fichiers, ne manquent jamais
aucune partie d'un refactoring. Le but d'un commit est de documenter une étape
atomique dans le processus par lequel le code évolue d'un état à un autre. Le
but d'un change log est de documenter les différences notables entre ces
états.
La différence entre des bons commentaires et le code lui-même est la même que
celle entre un change log et les journaux git: l'un décrit le *pourquoi*,
l'autre le comment.
### Les change logs peuvent-ils être parsés automatiquement ?
C'est difficile, parce que les gens suivent des formats et utilisent des noms
de fichiers très différents.
[Vandamme][vandamme] est une Ruby gem
créée par l'équipe [Gemnasium][gemnasium] qui parse les change logs de
beaucoup (mais pas tous) de projets open source.
### Pourquoi cette alternance entre les graphies "CHANGELOG" et "change log" ?
"CHANGELOG" est le nom pour le fichier même. C'est un peu imposant, mais dû à
une convention historique suivie par beaucoup de projets open source. Il
existe d'autres fichiers similaires, par exemple : [`README`][README],
[`LICENSE`][LICENSE], and [`CONTRIBUTING`][CONTRIBUTING].
L'écriture en majuscule (qui dans les vieux systèmes d'exploitation faisait
apparaître ces fichiers en haut) de ces noms de fichiers est utilisée pour
attirer l'attention sur eux. Puisqu'ils font partie des méta-données
importantes du projet, ils pourraient être utiles à quiconque voulant y
l'utiliser ou y contribuer, tout comme les
[badges de projet open source][shields].
Quand j'utilise la graphie "change log", je fais référence à la fonction de ce
fichier: journaliser les changements.
### Qu'en est-il des publications "yanked" ?
Les publications yanked sont des version qui ont dû être retirées du fait d'un
sérieux bug ou d'un problème de sécurité. Souvent ces version n'apparaissent
même pas dans les change logs. Elles devraient. Voilà comment les afficher:
`## 0.0.5 - 2014-12-13 [YANKED]`
Le tag `[YANKED]` n'est pas mis en avant pour rien. C'est important pour les
gens de le remarquer. Puisqu'il est entouré par des crochets, c'est aussi plus
facile à parser pour un programme.
### Devriez-vous réécrire un change log ?
Bien sûr. Il y a toujours de bonnes raisons d'améliorer un change log.
J'ouvre souvent des pull requests pour ajouter des publications manquantes sur
des projets open source avec des change logs non-maintenus.
Il est aussi possible que vous découvriez que vous aviez oublié de mentionner
un changement majeur dans les notes de version. Il est évidemment important
que vous mettiez votre change log à jour dans ce cas.
### Comment puis-je contribuer ?
Ce document n'est pas la **vérité**; c'est mon opinion soigneusement
réfléchie, accompagnée d'informations et d'exemples que j'ai rassemblés.
Bien que je fournisse un véritable [CHANGELOG][] sur [le dépôt GitHub][gh],
je n'ai volontairement pas créé de véritable *publication* ou de liste précise
de règles à suivre (comme le fait [SemVer.org][semver], par exemple).
C'est parce que je veux que notre communauté atteigne un consensus. Je crois
que la discussion est aussi importante que le résultat final.
Donc s'il vous plaît, [**mettez-vous y**][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/

176
source/it-IT/0.3.0/index.html.haml Normal file
View File

@ -0,0 +1,176 @@
---
description: Keep a Changelog
title: Keep a Changelog
language: it-IT
---
:markdown
# Mantenere un CHANGELOG
## Non lasciate che i vostri amici copino e incollino i git log nei CHANGELOG ™
### Cos'è un change log?
Un change log è un file che contiene una lista curata e ordinata cronologicamente
delle modifiche degne di nota per ogni versione di un progetto.
%pre.changelog= File.read("CHANGELOG.md")
:markdown
### A cosa serve un change log?
Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche
importanti sono state fatte tra ogni release (o versione) del progetto.
### Perché dovrebbe importarmi?
Perché gli strumenti software sono fatti per le persone.
Se non ti importa, perché contribuisci all'open source?
Di certo ci deve essere un "kernel" (ha!) di interesse
da qualche parte in quel tuo amorevole cervello.
[Nel podcast "The Changelog" con Adam Stacoviak e Jerod Santo][thechangelog]
(titolo appropriato, vero?) ho parlato del perché maintainer e contribuenti
dovrebbero esserne interessati, e delle motivazioni dietro a questo progetto.
Se avete tempo (1:06), vale la pena ascoltarlo.
### Come si può fare un buon change log?
Sono contento che tu l'abbia chiesto.
Un buon change log è guidato dai seguenti principi:
- È fatto per umani, non macchine, quindi la leggibilità è cruciale.
- Facile da linkare ad altre sezioni (da cui il Markdown invece che testo normale).
- Una sotto-sezione per ogni versione.
- Elenca le release in ordine cronologico inverso (quelle più recenti all'inizio).
- Scrive tutte le date nel formato `YYYY-MM-DD`. (Esempio: `2012-06-02` sta per `2 Giugno 2012`). È internazionale, [sensato](http://xkcd.com/1179/), e indipendente dalla lingua.
- Dichiara esplicitamente se il progetto segue il [Semantic Versioning][semver].
- Ogni versione dovrebbe:
- Elencare la sua data di rilascio nel formato sopra specificato.
- Raggruppare le modifiche per descrivere il loro impatto sul progetto, come segue:
- `Added` per le nuove funzionalità.
- `Changed` per le modifiche a funzionalità esistenti.
- `Deprecated` per vecchie feature stabili che verranno rimosse nelle future release.
- `Removed` per funzionalità precedentemente deprecate rimosse in questa release.
- `Fixed` per tutti i bug fix.
- `Security` per invitare gli utilizzatori ad aggiornare in caso di vulnerabilità.
### Come posso minimizzare lo sforzo richiesto?
Usa sempre una sezione `"Unreleased"` all'inizio per tenere traccia di qualsiasi modifica.
Questo serve per due scopi:
- La gente può vedere quali modifiche si può aspettare in future release
- Ad una nuova release, si deve solo sostituire `"Unreleased"` con il numero di versione
e aggiungere una nuova sezione `"Unreleased"` all'inizio.
### Cosa fa piangere gli unicorni?
Bene...vediamo un po'.
- **Copia&incolla un diff di commig log.** Non fatelo, così non aiutate nessuno.
- **Non enfatizzare le funzioni deprecate.** Quando le persone aggiornano da una versione ad un'altra,
dovrebbe essere dolorosamente chiaro quando qualcosa si romperà.
- **Date in formati specifici per regione.** Negli Stati Uniti si mette prima il mese nelle date
("06-02-2012" sta per 2 Giugno 2012, che non ha senso), mentre molte persone
nel resto del mondo scrivono un robotico "2 June 2012", ma lo pronunciano diversamente.
"2012-06-02" funziona con la logica dal più grande al più piccolo, non ha sovrapposizioni
ambigue con altri formati di date, ed è uno [standard ISO](http://www.iso.org/iso/home/standards/iso8601.htm).
Per tutti questi motivi, è il formato di date raccomandato per i change log.
C'è di più. Aiutatemi a collezionare queste "lacrime di unicorno" [aprendo una "issue"][issues]
o una pull request.
### Esiste un formato standard per i change log?
Purtroppo no. Calma. So che state furiosamente correndo a cercare quel link
alla guida di stile per i change log GNU, o alle linee guida per or il file a due paragrafi GNU NEWS.
La guida GNU è un buon punto di partenza, ma è tristemente ingenuo.
Non c'è nulla di male nell'essere ingenuo, ma quando le persone cercano una guida, questa caratteristica
è raramente d'aiuto. Specialmente se ci sono molte situazioni e casi limite da gestire.
Questo progetto [contiene ciò che spero diventerà una migliore convenzione per i file CHANGELOG][CHANGELOG].
Non credo che lo status quo sia sufficientemente buono, e penso che noi, come comunità,
possiamo arrivare a convenzioni migliori se tentiamo di estrarre le pratiche migliori
da progetti software reali. Vi consiglio di guardarvi intorno e ricordare che
[ogni discussione e suggerimento per migliorare sono sempre benvenuti][issues]!
### Come si dovrebbe chiamare il file contenente il change log?
Se non l'avete dedotto dall'esempio qui sopra, `CHANGELOG.md` è la convenzione migliore finora.
Alcuni progetti usano anche `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc.
È un disastro. Tutti questi nomi contribuiscono solo a rendere più difficile trovarlo.
### Perché la gente non si limita ad usare diff di `git log`?
Perché i log diff sono pieni di rumore, per loro natura. Non potrebbero creare un change log
decente nemmeno in un ipotetico progetto gestito da perfetti umani che non fanno mai errori
di digitazione, non dimenticano mai di fare commit dei nuovi file, non dimenticano mai
alcuna parte di un refactoring.
Lo scopo di un commit è di documentare un passo atomico nel processo di evoluzione del codice
da uno stato ad un altro. Lo scopo di un change log è di documentare le differenze
degne di nota tra questi stati.
La differenza tra un change log e un commit log è
come la differenza tra un buon commento nel codice e il codice stesso:
uno descrive il *perché*, l'altro il come.
### Si possono analizzare automaticamente i change log?
È difficile, perché le persone usano formati e nomi di file profondamente diversi.
[Vandamme][vandamme] è una Ruby gem
creata dal team [Gemnasium][gemnasium] ed è in grado di fare il parsing dei
change log di molti (ma non tutti) i progetti open source.
### Perché si alterna tra i nomi "CHANGELOG" e "change log"?
"CHANGELOG" è il nome del file. È un po' invadente ma è una
convenzione storica seguita da molti progetti open source.
Altri esempi di file simili includono [`README`][README], [`LICENSE`][LICENSE],
e [`CONTRIBUTING`][CONTRIBUTING].
I nomi in maiuscolo (che su vecchi sistemi operativi erano ordinati per primi)
vengono usati per attirare l'attenzione su di essi. Poiché sono metadati
importanti relativi al progetto, possono essere utili per chiunque voglia usarlo
o contribuire ad esso, un po' come i [badge dei progetti open source][shields].
Quando mi riferisco a un "change log", sto parlando della funzione di questo file:
registrare le modifiche.
### Cosa sono le release "yanked"?
Le release "yanked" sono versioni che sono state rimosse a causa di bug seri
o problemi di sicurezza. Spesso queste versioni non appaiono nei change
log. Invece dovrebbero esserci, nel seguente modo:
`## 0.0.5 - 2014-12-13 [YANKED]`
L'etichetta `[YANKED]` è in maiuscolo per un motivo. È importante che la gente la noti.
Poiché è racchiusa tra parentesi quadre è anche più semplice da riconoscere nel parsing automatizzato.
### Si dovrebbe mai modificare un change log?
Certo. Ci sono sempre buoni motivi per migliorare un change log. Io apro regolarmente
delle pull request per aggiungere release mancanti ai progetti open source che non mantengono
correttamente i change log.
È anche possibile che si scopra di aver dimenticato di annotare una modifica
non retro-compatibile nelle note per una versione. Ovviamente è importante aggiornare
il change log in questo caso.
### Come posso contribuire?
Questo documento non è la **verità assoluta**; è solo la mia attenta
opinione, arricchita dalle informazioni ed esempi che ho raccolto.
Anche se fornisco un [CHANGELOG][] reale sul [repository GitHub][gh],
ho volutamente evitato di creare una *release* o una chiara lista di regole
da seguire (come fa, ad esempio, [SemVer.org][semver]).
Questo è perché voglio che la nostra comunità raggiunga un consenso. Credo che
la discussione sia importante almeno quanto il risultato finale.
Quindi per favore [**partecipate**][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/

3
source/layouts/layout.html.haml
View File

@ -44,8 +44,7 @@
%p.about
#{link_to "Typed", "https://github.com/olivierlacan/keep-a-changelog/"}
with trepidation by
#{link_to "Olivier Lacan", "http://olivierlacan.com/"} from
#{link_to "Code School", "https://www.codeschool.com/"}.
#{link_to "Olivier Lacan", "http://olivierlacan.com/"}.
- unless config.gauges_id.blank?
:javascript

64
source/pt-BR/0.3.0/index.html.haml
View File

@ -8,14 +8,14 @@ version: 0.3.0
:markdown
# Mantenha um CHANGELOG
## Não deixe seus amigos despejar logs de commits em CHANGELOGs™
## Não deixe seus amigos despejarem 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
cronologicamente, de mudanças significativas para cada versão de um projeto
open source.
%pre.changelog= File.read("CHANGELOG.md")
@ -26,11 +26,11 @@ version: 0.3.0
Para facilitar para os usuários e contribuidores verem precisamente quais
mudanças significativas foram realizadas entre cada versão publicada.
### Por quê eu deveria me importar?
### Por que eu deveria me importar?
Porque softwares são feitos para pessoas. Se você não liga, porque está
contribuindo a projetos open source? Certamente deve haver um fundo de
carinho em algum lugar dessa sua cabeçinha.
carinho em algum lugar desse seu amável cerebrinho.
Eu [conversei com Adam Stacoviak e Jerod Santo no podcast do The
Changelog][thechangelog] (faz sentido, hein?) sobre o por quê mantenedores e
@ -74,17 +74,17 @@ version: 0.3.0
- As pessoas podem ver quais mudanças elas podem esperar em publicações
futuras.
- No momento da publicação, você tem que somente mudar Não publicado para o
- No momento da publicação, você tem que somente mudar `Unreleased` para o
número de versão e adicionar um novo cabeçalho `Unreleased` no topo.
### O que faz os unicórnios chorarem?
Tudo bem...vamos lá.
- Despejar logs de commits. Simplesmente não faça isso, você não está
- Despejar logs de commits. Simplesmente não faça isso, não está
ajudando ninguém.
- Não dar ênfase nas descontinuações. Quando as pessoas atualizam de uma
versão para outra, deve ser incrivelmente claro quando algo irá quebrar.
versão para outra, deve ser dolorosamente claro quando algo irá quebrar.
- Datas em formatos específicos de uma região. Nos Estados Unidos, as pessoas
colocam o mês primeiro ("06-02-2012" para 2 de Junho de 2012, o que *não*
faz sentido), enquanto muitos no resto do mundo escrevem em aspecto
@ -101,17 +101,16 @@ version: 0.3.0
Infelizmente, não. Calma. Eu sei que você está indo impetuosamente achar
aquele link do guia de estilo de *change log* GNU, ou o arquivo "guideline"
de dois paragráfos GNU NEWS. O estilo GNU é um bom começo mas é ingênuo. Não
há nada de errado em ser ingênuo mas quando as pessoas precisam de orientação
raramente ajuda. Especialmente quando existem muitas situações excepcionais
para lidar.
de dois paragráfos de GNU NEWS. O estilo GNU é um bom começo mas é ingênuo.
Não há nada de errado em ser ingênuo mas quando as pessoas precisam de
orientação isso raramente ajuda. Especialmente quando existem muitas
situações excepcionais e casos extremos com os quais se deve lidar.
Este projeto [contém o que eu espero se tornar um melhor padrão de arquivo
CHANGELOG][CHANGELOG] para todos projetos open source. Pode a comunidade open
source aprender com seus erros e não agir como se os dez mandamentos foram
escritos a muito tempo atrás e estavam inteiramente certos? Tudo bem. Então
por favor dê um olhada e lembre que [discussões e sugestões de melhorias são
bem-vindas][issues]!
CHANGELOG][CHANGELOG]. Não acho que o status é bom o suficiente, e acho que
como uma comunidade nós podemos definir melhores padrões se tentarmos extrair
boas práticas de projetos de software reais. Então por favor dê um olhada e
lembre que [discussões e sugestões para melhorias são bem-vindas][issues]!
### Qual deve ser o nome do arquivo *change log*?
@ -122,12 +121,21 @@ version: 0.3.0
`History.md`, `NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`,
`RELEASE.md`, `releases.md`, etc.
É uma bagunça. Todos esses nome só dificultam as pessoas acharem.
É uma bagunça. Todos esses nome só dificultam que as pessoas o achem.
### Por quê as pessoas não podem simplesmente utilizar `git log`?
Porque os logs do Git são cheios de ruído — por natureza. Eles não poderiam
escrever um change log adequado mesmo em um projeto hipotético desenvolvido
por humanos perfeitos que nunca cometem erros de grafia, nunca esquecem de
realizar commit de novos arquivos e nunca esquecem de nenhuma parte da
refatoração. O propósito de um commit é documentar um passo atômico no
processo no qual o código evolui de um estado a outro. O propósito de um
change log é documentar diferenças notáveis entre estes estados.
Porque logs de commit são cheios de distrações. Podemos realmente esperar que
cada commit do projeto seja significativo e auto-explicativo? Só em sonho.
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
outro o como.
### Podem os *change logs* ser automaticamente interpretados?
@ -144,10 +152,10 @@ version: 0.3.0
similares de arquivo incluem [`README`][README], [`LICENSE`][LICENSE], e
[`CONTRIBUTING`][CONTRIBUTING].
O nome em letras maiúsculas (o que em sistemas operacionais antigos faziam
estes arquivos serem mantidos no topo) é utilizado para chamar atenção a
eles. Já que eles são importante metadados sobre o projeto, eles podem ser
úteis a qualquer um pretendendo usar ou contribuir com ele, assim como os [as
O nome em letras maiúsculas (o que, em sistemas operacionais antigos, fazia
estes arquivos ficarem no topo da lista) é utilizado para chamar atenção para
eles. Já que são importante metadados sobre o projeto, eles podem ser úteis
a qualquer um pretendendo usar ou contribuir com ele, assim como os [as
badges de projeto open source][shields].
Quando eu me refiro a "*change log*", eu estou falando sobre a função deste
@ -164,6 +172,16 @@ version: 0.3.0
A tag `[YANKED]` é chamativa por uma razão. É importante que as pessoas a
notem. E já que é cercada por colchetes é mais fácil detectá-la
programaticamente.
### Se você deveria reescrever um change log?
Claro. Sempre existem boas razões para melhorar um change log. Eu abro os pull
requests regularmente para adicionar releases que faltam a projetos open source
com change logs sem manutenção.
É também possível que você descubra que esqueceu de registrar uma mudança
crucial nas anotações de uma versão. É obviamente importante que você atualize
seu change log neste caso.
### Como eu posso contribuir?

183
source/sl/0.3.0/index.html.haml Normal file
View File

@ -0,0 +1,183 @@
---
description: Keep a Changelog
title: Keep a Changelog
language: sl
version: 0.3.0
---
:markdown
# Vzdržujte dnevnik sprememb oz. CHANGELOG
## Ne dopustite, da vaši prijatelji odlagajo git dnevnike v CHANGELOG™
Verzija **#{current_page.metadata[:page][:version]}**
### Kaj je dnevnik sprememb?
Dnevnik sprememb je datoteka, ki vsebuje kuriran, kronološko urejen
seznam opaznih sprememb za vsako verzijo projekta.
%pre.changelog= File.read("CHANGELOG.md")
:markdown
### Kaj je smisel dnevnika sprememb?
Za poenostavitev, da uporabniki in prispevajoči sodelavci natančno vidijo, katere
opazne spremembe so bile narejene med vsako izdajo (ali verzijo) projekta.
### Zakaj se truditi?
Ker so programska orodja za ljudi. Če vam to ni pomembno, zakaj
prispevate odprto kodnemu projektu? Zagotovo mora obstajati malenkost (hehe)
skrbnosti nekje v vaši lepi glavi.
Govorili smo z [Adam-om Stacoviak-om in Jerod-om Santo na temo Changelog-a][thechangelog]
(ustrezno, kajne?) podcast o tem zakaj bi se morali vzdrževalci in
sodelavci, ki prispevajo, truditi in o motivaciji za tem projektom.
Če imate na voljo nekaj časa (1:06), je odlično poslušanje.
### Kaj naredi dnevnik sprememb odličen?
Veseli me, da ste vprašali.
Dober dnevnik sprememb se drži teh načel:
- Je enostaven za ljudi, ne stroje, tako da je čitljivost ključnega pomena.
- Enostaven za povezavo kateri koli sekciji (torej Markdown pred golim besedilom).
- Ena pod-sekcija na verzijo.
- Seznam izdaj v obratnem kronološkem vrstnem redu (najnovejše na vrhu).
- Zapis vseh datumov v `YYYY-MM-DD` formatu. (Na primer: `2012-06-02` za `2. junij 2012`.) Je mednarnodno, [smiselno](http://xkcd.com/1179/) in neodvisno od jezika.
- Eksplicitna omemba ali projekt sledi [semantičnim verzijam][semver].
- Vsaka verzija bi morala:
- Imeti seznam njenih datumov izdaje v zgornjem formatu.
- Skupine sprememb, ki opisujejo njihove vplive na projekt, kot sledi:
- `Added` za nove lastnosti.
- `Changed` za spremembe obstoječih lastnosti.
- `Deprecated` za nekoč stabilne lastnosti, ki bodo odstranjene v prihajajočih verzijah.
- `Removed` za zastarele lastnosti, ki so odstranjene v tej izdaji.
- `Fixed` za kakršne koli popravke hroščev.
- `Security` za povabilo uporabnikom, da nadgradijo v primeru varnostnih ranljivosti.
### Kako zmanjšati potreben trud?
Vedno imejte `"Unreleased"` sekcijo na vrhu za sledenje katerih koli
sprememb.
To služi dvema namenoma:
- Ljudje lahko vidijo, katere spremembe lahko pričakujejo v prihajajočih izdajah
- Pri izdaji, morate tako samo spremembiti `"Unreleased"` v številko verzije
in dodati nov naslov `"Unreleased"` na vrh.
### Kaj spravi samoroga v jok?
Dobro … pojdimo skozi.
- **Odlaganje sprememb git dnevnikov poslanih sprememb.** Temu se izogibajte, saj s tem ne pomagate nikomur.
- **Nepoudarjanje zastarelosti.** Ko uporabniki nadgradijo iz ene verzije na
drugo, bi moralo biti enostavno jasno, ko nekaj ne bo več delovalo.
- **Datumi v lokalnih oblikah.** V ZDA, uporabniki dajo mesec na prvo mesto
("06-02-2012" za 2. junij, 2012, kar je brez smisla), medtem ko mnogi ostali
uporabniki drugod po svetu pišejo "2 June 2012" robotskega izgleda, vendar
izgovorijo to drugače. "2012-06-02" deluje logično po večini in se ne
prekriva na dvoumne načine z ostalimi oblikami datumov. To je tudi
[ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Tako je to
priporočljiva oblika datuma za dnevnike sprememb.
Tega je še več. Pomagajte zbrati te solze samoroga preko
[odprtja težave][issues]
ali zahtevka potega.
### Ali obstaja standardna oblika dnevnika sprememb?
Na žalost ne. Vendar mirno kri. Vem, da besno hitite najti to povezavo
v vodiču dnevnika sprememb GNU ali v datoteki dveh odstavkov "guideline" GNU
NEWS. Stilski vodič GNU je lep začetek, vendar je na žalost preveč enostaven.
S tem ni nič narobe, vendar ko uporabniki potrebujejo
vodič, je redko v pomoč. Posebej, ko je za reševati veliko
situacij in posebnih primerov.
Ta projekt [vsebuje, kar upamo, da bo postalo boljša datoteka konvencij CHANGELOG][CHANGELOG].
Mislimo, da status quo ni dovolj dober in mislimo, da lahko kot skupnost
naredimo boljšo konvencijo, če poskusimo izvleči dobre prakse iz
realnih programskih projektov. Prosimo, poglejte naokoli in si zapomnite, da
[diskusije in predlogi za izboljšave so dobrodošli][issues]!
### Kako se mora dnevnik sprememb imenovati?
Če niste uspeli razbrati iz zgornjega primera, je `CHANGELOG.md`
najboljša konvencija do sedaj.
Nekateri projekti uporabljajo tudi `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md` itd.
Gre za zmešnjavo. Vsa ta imena ljudem samo otežijo najti dnevnik sprememb.
### Zakaj uporabniki ne morejo uporabiti enostavno samo `git log` sprememb?
Ker so spremembe dnevnika polne šuma - privzeto. Lahko bi naredili ustrezen
dnevnik sprememb tudi v hipotetičnem projektu, ki ga poganjajo popolni ljudje, ki nikoli ne naredijo
napak, nikoli ne pozabijo poslati novih datotek in nikoli ne zamudijo nobenega dela refaktorizacije.
Razlog pošiljke (commit-a) je dokumentirati en atomičen korak v procesu preko katerega
se koda razvija iz enega stanja v drugo. Razlog dnevnika sprememb je
dokumentiranje omembe vrednih sprememb med temi stanji.
Kakor obstaja razlika med dobrimi komentarji in samo kodo,
tako je razlika med dnevnikom sprememb in dnevnikom git commit-a:
eden opisuje *zakaj*, drugi pa *kako*.
### Ali se da dnevnik sprememb samodejno razlčeniti?
Je težko, ker uporabniki sledijo divje različnim formatom in imenom datotek.
[Vandamme][vandamme] je Ruby gem,
ki ga je ustvarila ekipa [Gemnasium][gemnasium]. Razčlenjuje
mnoge (vendar ne vse) dnevnike sprememb odprto kodnih projektov.
### Zakaj razlikovanje med črkovanjem "CHANGELOG" in "change log"?
"CHANGELOG" je ime same datoteke. Je nekoliko glasno, vendar je to
zgodovinska konvencija, kateri sledi mnogo odprto kodnih projektov. Drugi
primeri podobnih datotek vključujejo [`README`][README], [`LICENSE`][LICENSE],
in [`CONTRIBUTING`][CONTRIBUTING].
Ime z velikimi črkami (kar je datoteko v starih operacijskih sistemih prikazalo na
vrhu) je uporabljeno, da se povleče pozornost nanje. Ker gre za pomembne
meta podatke o projektu, so lahko uporabne za kogarkoli, ki namerava uporabiti
ali prispevati, precej enako kot [značke odprto kodnih projektov][shields].
Ko se sklicujemo na "change log", govorimo o funkciji te
datoteke: beleženje sprememb.
### Kaj pa povlečene izdaje?
T.i. yanked ali povlečene izdaje so verzije, ki so bile primorane biti potegnjene zaradi resnega
hrošča ali varnostne težave. Pogostokrat se te verzije niti ne pojavijo v
dnevnikih sprememb. Vendar bi se morale. Prikazane bi morale biti sledeče:
`## 0.0.5 - 2014-12-13 [YANKED]`
Oznaka `[YANKED]` je izpisana z velikimi črkami z razlogom. Pomembno je, da jo uporabniki
opazijo. Ker je obdana z oglatimi oklepaji, jo je tudi enostavnejše razčleniti
programsko.
### Ali bi morali kadarkoli prepisati dnevnik sprememb?
Seveda. Vedno obstajajo dobri razlogi, kako izboljšati dnevnik sprememb. Odpiranje
zahtevkov potegov je pogostokrat priporočljivo, da se doda manjkajoče izdaje
odprtokodnih projektov z nevzdrževanimi dnevniki sprememb.
Možno je tudi, da odkrijete, da ste pozabili nasloviti pomembne spremembe
v opombah verzije. Očitno je pomembno, da vaš
dnevnik sprememb v tem primeru posodobite.
### Kako lahko pomagam?
Ta dokument ni **dejstvo**; je osebno temeljito premišljeno
mnenje, skupaj z informacijami in primeri, ki smo jih zbrali.
Čeprav ponujamo dejanski [CHANGELOG][] v [GitHub repozitoriju][gh],
namenoma ni ustvarjene primerne *izdaje* ali jasnega seznama pravil
za sledenje (kot ima to npr. [SemVer.org][semver]).
To je zato, ker želimo, da naša skupnost doseže soglasje. Verjamemo,
da je razprava tako pomembna kot končni rezultat.
Torej, prosimo [**pridružite se**][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/

34
source/sv/0.3.0/index.html.haml
View File

@ -21,15 +21,15 @@ version: 0.3.0
:markdown
### Vad är meningen med en ändringslogg?
För att göra det enkelt för användare och medarbetare att se exakt vilka
viktiga ändringar som har gjort mellan varje utgåva (eller version) av projektet.
viktiga ändringar som har gjorts mellan varje utgåva (eller version) av projektet.
### Varför ska jag bry mig?
Därför att mjukvaruverktyg är för människor. Om du inte bryr dig, varför
bidrar du till öppen källkod? Visst finns det väl någon del i din vackra
hjärna som bryr sig.
Jag [pratade med Adam Stacoviak och Jerod Santo på The Changelog][thechangelog]
(passande, eller hur?) podcast om varför ansvariga och bidragsgivare bör bry sig,
Jag [pratade med Adam Stacoviak och Jerod Santo från podcasten The Changelog][thechangelog]
(passande, eller hur?) om varför ansvariga och bidragsgivare bör bry sig,
och motiveringen bakom detta projekt.
Om du kan avvara lite tid (1:06), rekommenderar jag att lyssna på det.
@ -41,23 +41,23 @@ version: 0.3.0
- Den är skapad för människor, inte maskiner, så läsbarhet är avgörande.
- Lätt att länka till valfri sektion (därav Markdown framför klartext).
- En undersektion per version.
- Lista utgåvor i omvänd kronologisk ordning (nyast högst upp).
- Skriv alla datum på formatet `YYYY-MM-DD`
- Listar utgåvor i omvänd kronologisk ordning (nyast högst upp).
- Anger alla datum på formatet `YYYY-MM-DD`
(exempel: `2012-06-02` för 2:a juni 2012). Det är internationellt,
[förnuftigt](http://xkcd.com/1179/) och språkoberoende.
- Ange uttryckligen att projektet följer [Semantisk versionshantering][SemVer].
- Anger uttryckligen om projektet följer [Semantisk versionshantering][SemVer].
- Varje version bör:
- Ange datum då utgåvan släptes på formatet angivet ovan.
- Ange datum då utgåvan släpptes på formatet angivet ovan.
- Gruppera ändringar för att beskriva deras inverkan på projektet enligt följande:
- `Added` för nya funktioner.
- `Changed` för ändringar på existerande funktionalitet.
- `Deprecated` för tidigare stabila funktioner som tas bort i nästa utgåva.
- `Removed` för funktioner tidigare markerade som `deprecated` som tas bort i denna version.
- `Removed` för funktioner tidigare markerade som `Deprecated` som tas bort i denna version.
- `Fixed` för buggfixar.
- `Security` för att uppmana användare att uppgradera vid fall av sårbarheter.
### Hur kan jag minimera den insats som krävs?
Ha alltid en sektion kallas `"Unreleased"` högst upp för att hålla reda på
Ha alltid en sektion kallad `"Unreleased"` högst upp för att hålla reda på
alla ändringar.
Detta tjänar två syften:
@ -70,11 +70,11 @@ version: 0.3.0
Okej...låt oss gå genom det.
- **Dumpa ut en diff från commit-loggen.** Gör helt enkelt inte så, du hjälper ingen.
- **Inte betona `deprecations`.** När folk uppgraderar från en version till
- **Inte betona `deprecations`.** När användare uppgraderar från en version till
en annan ska det vara smärtsamt uppenbart om något förväntas gå sönder.
- **Datum i region-specifikt format.** I USA lägger folk månaden föst
- **Datum i region-specifikt format.** I USA lägger folk månaden först
("06-02-2012" för 2:a juni 2012, vilket bara är *konstigt*), medan många
andra runt om i världen skriver "2 June 2012" men uttala det annorlunda.
andra runt om i världen skriver "2 June 2012" men uttalar det annorlunda.
"2012-06-02" fungerar logiskt från största till minsta, inte överlappar på ett
tvetydligt sätt med andra datumformat, och det är en
[ISO-standard](http://www.iso.org/iso/home/standards/iso8601.htm). Dessutom
@ -87,7 +87,7 @@ version: 0.3.0
### Finns det ett standardformat på ändringsloggar?
Tyvärr inte. Men lugn. Jag vet att du frustrerad kommer att rusa iväg för att hitta
den där länken till GUS:s format för ändringsloggar, eller den två stycken långa
den där länken till GNU:s format för ändringsloggar, eller den två stycken långa
GNU NEWS-filen med "guideline". Stilguiden från GNU är en bra start, men den är
tyvärr allt för naiv. Det är inget fel med att vara naiv, men när människor
behöver vägledning är det inte speciellt hjälpsamt. Speciellt när det är många
@ -119,7 +119,7 @@ version: 0.3.0
På samma sätt som det är skillnad mellan bra kommentarer och själva koden,
är det skillnad mellan ändringsloggen och commit-loggen:
en beskriver "varför" och den andra "hur".
en beskriver *varför* och den andra *hur*.
### Kan ändringsloggar bli automatiskt tolkade?
Det är svårt då människor följer vitt olika format och filnamn.
@ -128,9 +128,9 @@ version: 0.3.0
skapad av gruppen bakom [Gemnasium][gemnasium] som tolkar många (men inte alla)
ändringsloggar för öppen källkod.
### Varför alternerar du mellan att skriva det som "CHANGELOG" och "ändringslogg"?"
### Varför alternerar du mellan att skriva det som "CHANGELOG" och "ändringslogg"?
"CHANGELOG" är namnet på själva filen. Det sticker ut lite, men det är en
historisk konvention använt i många öppen källkodsprojekt. Andra
historisk konvention använt i många öppna källkodsprojekt. Andra
exempel på liknande filer är [`README`][README], [`LICENSE`][LICENSE]
och [`CONTRIBUTING`][CONTRIBUTING].
@ -156,7 +156,7 @@ version: 0.3.0
### Borde du någonsin förändra en ändringslogg?
Självklart. Det finns alltid en bra anlending att förbättra en ändringslogg.
Jag öppnar regelbundet pull requests för att lägga till saknade utgåvor
för öppen källkodsprojekt som inte tar hand om sin ändringslogg.
för öppna källkodsprojekt som inte tar hand om sin ändringslogg.
Det kan också hända att du upptäcker att du glömt att ta upp en icke
bakåtkompatibel förändring i en version. I sådana fall är det självklart

14
source/zh-CN/0.3.0/index.html.haml
View File

@ -24,12 +24,12 @@ version: 0.3.0
为了让用户和开发人员更好知道每一个版本有哪些区别。
### 为何我要在乎呢？
因为归根结底软件是为人提供的。既然你不关心人，哪么为何写软件呢？
因为归根结底软件是为人提供的。既然你不关心人，那么为何写软件呢？
多少你还是要关心你的受众。
本文档原作者和另外两个人的一个[播客][thechangelog]向大家介绍了，
为何代码的管理者和开发者应该在乎更新日志。如果你有一小时时间和很好的英文听力本领，
不放听听。
不妨听听。
### 怎么定义好的更新日志
好问题！
@ -56,7 +56,7 @@ version: 0.3.0
### 怎么尽可能减少耗费的精力？
永远在文档最上方提供一个'Unreleased' 未发布区域，来记录当前的变化。
这佯作有两大意义。
这样作有两大意义。
- 大家可以看到接下来会有什么变化
- 在发布时，只要把'Unreleased'改为当前版本号，然后再添加一个新的'Unreleased'就行了
@ -74,7 +74,7 @@ version: 0.3.0
### 世界上不是有标准的更新日志格式吗？
貌似GNU或者GNU NEWS还是提过些规范的，事实是它们太过简陋了。
开发有那么多中情况，采用那样的规范，确实是不太合适的。
开发有那么多种情况，采用那样的规范，确实是不太合适的。
这个项目提供的[规范][CHANGELOG]是作者本人希望能够成为世界规范的。
作者不认为当前的标准足够好，而且作为一个社区，我们是有能力提供更棒的规范。
@ -92,15 +92,15 @@ version: 0.3.0
### 为何不直接记录`git log`?
因为git日志一定是乱糟糟的。哪怕一个最理想的由完美的程序员开发的提交的，哪怕一个
从不忘记每次提交全部文件，不写错别字，不忘记重构每一个部分——也无法保证git日志完美无瑕。
因为git日志一定是乱糟糟的。哪怕一个最理想的由完美的程序员开发和提交的，哪怕一个
从不忘记每次提交全部文件，不写错别字，不忘记重构每一个部分，也无法保证git日志完美无瑕。
况且git日志的核心在于记录代码的演化，而更新日志则是记录最重要的变更。
就像注释之于代码，更新日志之于git日志。前者解释*为什么*，而后者说明*发生了什么*。
### 更新日志能机器识别吗？
非常困难，因为有各种不同的文件格式和其他规范。
非常困难，因为有各种不同的文件格式和其它规范。
[Vandamme][vandamme]是一个Ruby程序（由[Gemnasium][gemnasium]团队制作），可以解析
好多种（但绝对不是全部）开源库的更新日志。

100
source/zh-TW/0.3.0/index.html.haml
View File

@ -8,12 +8,12 @@ version: 0.3.0
:markdown
# 如何維護更新日誌
## 更新日誌絕對不應該是git日誌的堆砌物
## 更新日誌絕對不應該是 git 日誌的堆砌物
Version **#{current_page.metadata[:page][:version]}**
### 更新日誌是什麽？
更新日誌（Change Log）是壹個由人工編輯，以時間為倒敘的列表。
更新日誌（Change Log）是一個由人工編輯，以時間為倒敘的列表。
這個列表記錄所有版本的重大變動。
@ -21,116 +21,116 @@ version: 0.3.0
:markdown
### 為何要提供更新日誌？
為了讓用戶和開發人員更好知道每壹個版本有哪些區別。
為了讓用戶和開發人員更好知道每一個版本有哪些區別。
### 為何我要在乎呢？
因為歸根結底軟件是為人提供的。既然妳不關心人，哪麽為何寫軟件呢？
多少妳還是要關心妳的受眾。
因為歸根結底軟體是為人提供的。既然你不關心人，那麽為何寫軟體呢？
多少你還是要關心你的受眾。
本文檔原作者和另外兩個人的壹個[播客][thechangelog]向大家介紹了，
為何代碼的管理者和開發者應該在乎更新日誌。如果妳有壹小時時間和很好的英文聽力本領，
不放聽聽。
本文檔原作者和另外兩個人的一個[部落格][thechangelog]向大家介紹了，
為何程式碼的管理者和開發者應該在乎更新日誌。如果你有一小時時間和很好的英文聽力本領，
不妨聽聽。
### 怎麽定義好的更新日誌
好問題！
壹個好的更新日誌，壹定滿足：
一個好的更新日誌，一定滿足：
- 給人而不是機器寫的。記住，要說人話。
- 快速跳轉到任意段。所以采用markdown格式
- 壹個版本對應壹個章節。
- 最新的版本在上，最老的在下面。
- 所有日期采用'YYYY-MM-DD'這種規範。（例如北京奧運會的2008年8月8日是2008-08-08）這個是國際通用，任何語言
都能理解的，並且還被[xkcd](http://xkcd.com/1179/)推薦呢！
- 快速跳轉到任意段。所以採用 markdown 格式
- 一個版本對應一個章節。
- 最新的版本在上面，最舊的在下面。
- 所有日期採用 'YYYY-MM-DD' 這種規範。（例如北京奧運會的 2008 年 8 月 8 日是 2008-08-08）這個是國際通用，任何語言
都能理解的，並且還被 [xkcd](http://xkcd.com/1179/) 推薦呢！
- 標出來是否遵守[語義化版本格式][semver]
- 每壹個軟件的版本必須：
- 每一個軟體的版本必須：
- 標明日期（要用上面說過的規範）
- 標明分類（采用英文）。規範如下：
- 標明分類（採用英文）。規範如下：
- 'Added' 添加的新功能
- 'Changed' 功能變更
- 'Deprecated' 不建議使用，未來會刪掉
- 'Removed' 之前不建議使用的功能，這次真的刪掉了
- 'Fixed' 改的bug
- 'Security' 改的有關安全相關bug
- 'Fixed' 修正的 bug
- 'Security' 修正了安全相關的 bug
### 怎麽盡可能減少耗費的精力？
永遠在文檔最上方提供壹個'Unreleased' 未發布區域，來記錄當前的變化。
這佯作有兩大意義。
永遠在文檔最上方提供一個 'Unreleased' 未發布區域，來記錄當前的變化。
這樣做有兩大意義。
- 大家可以看到接下來會有什麽變化
- 在發布時，只要把'Unreleased'改為當前版本號，然後再添加壹個新的'Unreleased'就行了
- 在發布時，只要把 'Unreleased' 改為當前版本號，然後再添加一個新的 'Unreleased' 就行了
### 吐槽環節到了
請妳壹定要註意：
請你一定要注意：
- **把git日誌扔到更新日誌裏。**看似有用，然並卵。
- **不寫'deprecations'就刪功能。**不帶這樣坑隊友的。
- **采用各種不靠譜日期格式** 2012年12月12日，也就中國人能看懂了。
- **把 git 日誌扔到更新日誌裏。**看似有用，然而並沒有什麼作用。
- **不寫 'deprecations' 就刪功能。**不帶這樣坑隊友的。
- **採用各種不可靠的日期格式** 2012 年 12 月 12 日，也就懂中文的人能看得懂了。
如果妳還有要吐槽的，歡迎留[issue][issues]或者直接PR
如果你還有要吐槽的，歡迎留 [issue][issues] 或者直接 PR
### 世界上不是有標準的更新日誌格式嗎？
貌似GNU或者GNU NEWS還是提過些規範的，事實是它們太過簡陋了。
開發有那麽多中情況，采用那樣的規範，確實是不太合適的。
貌似 GNU 或者 GNU NEWS 還是提過些規範的，事實是它們太過簡陋了。
開發有那麽多中情況，採用那樣的規範，確實是不太合適的。
這個項目提供的[規範][CHANGELOG]是作者本人希望能夠成為世界規範的。
作者不認為當前的標準足夠好，而且作為壹個社區，我們是有能力提供更棒的規範。
如果妳對這個規範有不滿的地方，不要忘記還可以[吐槽][issues]呢。
作者不認為當前的標準足夠好，而且作為一個社區，我們是有能力提供更棒的規範。
如果你對這個規範有不滿的地方，不要忘記還可以[吐槽][issues]呢。
### 更新日誌文件名應該叫什麽？
我們的案例中給的名字就是最好的規範：`CHANGELOG.md`，註意大小寫。
我們的案例中給的名字就是最好的規範：`CHANGELOG.md`，注意大小寫。
像`HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`這麽
多文件名就太不統壹了。
像 `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md` 這麽
多文件名就太不統一了。
只會讓大家更難找到。
### 為何不直接記錄`git log`?
### 為何不直接記錄 `git log`?
因為git日誌壹定是亂糟糟的。哪怕壹個最理想的由完美的程序員開發的提交的，哪怕壹個
從不忘記每次提交全部文件，不寫錯別字，不忘記重構每壹個部分——也無法保證git日誌完美無瑕。
況且git日誌的核心在於記錄代碼的演化，而更新日誌則是記錄最重要的變更。
因為 git 日誌一定是亂糟糟的。哪怕一個最理想的由完美的程序員開發的提交的，哪怕一個
從不忘記每次提交全部文件，不寫錯別字，不忘記重構每一個部分——也無法保證 git 日誌完美無瑕。
況且 git 日誌的核心在於記錄代碼的演化，而更新日誌則是記錄最重要的變更。
就像註釋之於代碼，更新日誌之於git日誌。前者解釋*為什麽*，而後者說明*發生了什麽*。
就像註解之於程式碼，更新日誌之於 git 日誌。前者解釋*為什麽*，而後者說明*發生了什麽*。
### 更新日誌能機器識別嗎？
非常困難，因為有各種不同的文件格式和其他規範。
[Vandamme][vandamme]是壹個Ruby程序（由[Gemnasium][gemnasium]團隊制作），可以解析
好多種（但絕對不是全部）開源庫的更新日誌。
[Vandamme][vandamme] 是一支 Ruby 程式（由 [Gemnasium][gemnasium] 團隊制作），可以解析
很多種（但絕對不是全部）開源程式庫的更新日誌。
### 到底是CHANGELOG還是更新日誌
### 到底是 CHANGELOG 還是更新日誌
CHANGELOG是文件名，更新日誌是常用說法。CHANGELOG采用大寫是有歷史根源的。就像很多類似的文件
[`README`][README]， [`LICENSE`][LICENSE]，還有[`CONTRIBUTING`][CONTRIBUTING]。
CHANGELOG 是文件名，更新日誌是常用說法。CHANGELOG 採用大寫是有歷史根源的。就像很多類似的文件
[`README`][README]，[`LICENSE`][LICENSE]，還有 [`CONTRIBUTING`][CONTRIBUTING]。
采用大寫可以更加顯著，畢竟這是項目很重要的元信息。就像[開源徽章][shields]。
採用大寫可以更加顯著，畢竟這是項目很重要的 metadata。就像[開源徽章][shields]。
### 那些後來撤下的版本怎麽辦？
因為各種安全/重大bug原因被撤下的版本被標記'YANKED'。這些版本壹般不出現在更新日誌裏，但作者建議他們出現。
因為各種安全/重大 bug 原因被撤下的版本被標記 'YANKED'。這些版本一般不出現在更新日誌裏，但作者建議他們出現。
顯示方式應該是：
`## 0.0.5 - 2014-12-13 [YANKED]`
`[YANKED]`采用大寫更加顯著，因為這個信息很重要。而采用方括號則容易被程序解析。
`[YANKED]` 採用大寫更加顯著，因為這個訊息很重要。而採用方括號則容易被程式解析。
### 是否可以重寫更新日誌
當然。哪怕已經上線了，也可以重新更新更新日誌。有許多開源項目更新日誌不夠新，所以作者就會幫忙更新。
另外，很有可能妳忘記記錄壹個重大功能更新。所以這時候應該去重寫更新日誌。
另外，很有可能你忘記記錄一個重大功能更新。所以這時候應該去重寫更新日誌。
### 如何貢獻？
本文檔並不是**真理**。這只是原作者的個人建議，並且包括許多收集的例子。
哪怕[本開源庫][gh]提供壹個[更新日誌案例][CHANGELOG]，我刻意沒有提供壹個
哪怕[本開源庫][gh]提供一個[更新日誌案例][CHANGELOG]，我刻意沒有提供一個
過於苛刻的規則列表（不像[語義化版本格式][semver]）。
這是因為我希望通過社區達到統壹觀點，我認為中間討論的過程與結果壹樣重要。
這是因為我希望通過社區達到統一觀點，我認為中間討論的過程與結果一樣重要。
所以[歡迎貢獻][gh]。