mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-29 16:54:12 +02:00
Merge branch 'master' into translation_pt-br
This commit is contained in:
Samuel Tschiedel
GitHub
commit
6be9828c01
@ -1,7 +1,7 @@
|
||||
# Change Log
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](http://keepachangelog.com/)
|
||||
The format is based on [Keep a Changelog](http://keepachangelog.com/)
|
||||
and this project adheres to [Semantic Versioning](http://semver.org/).
|
||||
|
||||
## [Unreleased]
|
||||
@ -11,10 +11,13 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
|
||||
- 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
|
||||
|
||||
@ -5,12 +5,15 @@
|
||||
# ----- 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" => "简体中文",
|
||||
|
||||
177
source/cs/0.3.0/index.html.haml
Normal file
177
source/cs/0.3.0/index.html.haml
Normal 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/
|
||||
@ -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
210
source/fr/0.3.0/index.html.haml
Normal 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/
|
||||
@ -30,7 +30,7 @@ version: 0.3.0
|
||||
|
||||
Porque softwares são feitos para pessoas. Se você não liga, por que está
|
||||
contribuindo com projetos *open source*? Certamente deve haver um fundo de
|
||||
carinho em algum lugar dessa sua cabecinha.
|
||||
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 por que mantenedores e
|
||||
@ -74,7 +74,7 @@ version: 0.3.0
|
||||
|
||||
- As pessoas podem ver quais mudanças elas podem esperar em publicações
|
||||
futuras.
|
||||
- No momento da publicação, você apenas tem de mudar o `"A publicar"` para o
|
||||
- No momento da publicação, você apenas tem de mudar o `"Unreleased"`\`"A publicar"` para o
|
||||
número de versão e adicionar um novo cabeçalho `"Unreleased"`\`"A publicar"` no topo.
|
||||
|
||||
### O que faz os unicórnios chorarem?
|
||||
@ -124,10 +124,10 @@ version: 0.3.0
|
||||
|
||||
### Por que as pessoas não podem simplesmente utilizar `git log`?
|
||||
|
||||
Porque diffs de logs são cheios de ruído — por natureza. Eles não serviriam como
|
||||
um changelog mesmo em um projeto hipotético executado por humanos perfeitos, que
|
||||
nunca erraram uma letra, esqueceram de *commit'ar* um arquivo, nunca perderam nenhuma
|
||||
parte de um *refactoring*. O propósito de um *commit* é documentar um passo atômico no
|
||||
Porque os logs do Git são cheios de ruído — por natureza. Eles não serviriam como um
|
||||
changelog adequado mesmo em um projeto hipotético executado por humanos perfeitos, que
|
||||
nunca erram uma letra, nunca esquecem de *commitar* arquivos, nunca cometem deslizes
|
||||
em uma refatoração. O propósito de um *commit* é documentar um passo atômico no
|
||||
processo pelo qual o código evolui de um estado a outro. O propósito de um *changelog*
|
||||
é documentar as diferenças relevantes entre esses estados.
|
||||
|
||||
@ -150,10 +150,10 @@ version: 0.3.0
|
||||
[`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.
|
||||
Por conterem importantes metadados do projeto, *changelogs* podem ser úteis a
|
||||
qualquer um que pretenda utilizar ou contribuir com o projeto, assim como os [as
|
||||
badges de projeto *open source*][shields].
|
||||
estes arquivos ficarem no topo da lista) é utilizado para chamar atenção.
|
||||
Por conterem importantes metadados do projeto, *changelogs* são úteis a
|
||||
qualquer um que pretenda utilizar ou contribuir com o projeto, da maneira
|
||||
equivalente às [badges de projetos *open source*][shields].
|
||||
|
||||
Quando eu me refiro a "*changelog*", eu estou falando sobre a função desse
|
||||
arquivo: listar mudanças.
|
||||
@ -166,17 +166,19 @@ version: 0.3.0
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [YANKED]`
|
||||
|
||||
A tag `[YANKED]`/`[REMOVIDA]` é chamativa por uma razão. É importante que as pessoas a
|
||||
notem. Além disso, já que é cercada por colchetes, é mais fácil detectá-la programaticamente.
|
||||
A tag `[YANKED]`/`[REMOVIDA]` é chamativa por uma razão. É importante que
|
||||
as pessoas a notem. Além disso, já que é cercada por colchetes, é mais
|
||||
fácil detectá-la programaticamente.
|
||||
|
||||
### Devemos alterar o *changelog* em alguma circunstância?
|
||||
|
||||
Claro. Sempre existem bons motivos para melhorar um *changelog*. Eu regularmente
|
||||
abro *pull requests* para adicionar versões faltantes em projetos *open source* com
|
||||
*changelogs* abandonados.
|
||||
abro *pull requests* para adicionar versões faltantes em projetos *open source*
|
||||
com *changelogs* abandonados.
|
||||
|
||||
Também é possível que você perceba que se esqueceu de registrar mudanças importantes
|
||||
nas notas de uma versão. É obviamente importante que você atualize seu *changelog* nesse caso.
|
||||
Também é possível que você perceba que se esqueceu de registrar mudanças
|
||||
importantes nas notas de uma versão. É obviamente importante que você atualize
|
||||
seu *changelog* nesse caso.
|
||||
|
||||
### Como eu posso contribuir?
|
||||
|
||||
@ -189,7 +191,7 @@ version: 0.3.0
|
||||
Fiz isso porque eu gostaria que nossa comunidade chegasse a um consenso. Eu
|
||||
acredito que a discussão é tão importante quanto o resultado final.
|
||||
|
||||
Então por favor [entre em campo][gh].
|
||||
Então, por favor, [entre em campo][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
|
||||
|
||||
183
source/sl/0.3.0/index.html.haml
Normal file
183
source/sl/0.3.0/index.html.haml
Normal 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/
|
||||
@ -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
|
||||
|
||||
@ -8,7 +8,7 @@ version: 0.3.0
|
||||
:markdown
|
||||
# CHANGELOG dosyası kullanın
|
||||
|
||||
## Arkadaşlarınızın git kayıtlarını CHANGELOG dosyalarına boşaltmasını engelleyin™
|
||||
## Arkadaşlarınızın, git kayıtlarını CHANGELOG dosyalarına yığmasını engelleyin™
|
||||
|
||||
### Nedir bu değişiklik kayıtları?
|
||||
Değişiklik kayıtları bir proje için özel olarak hazırlanmış, tarihsel sıralamayla
|
||||
@ -26,7 +26,7 @@ version: 0.3.0
|
||||
katkıda bulunuyorsunuz ki? Mutlaka sevimli beyninizin bir yerlerinde bunu önemseyen
|
||||
bir çekirdek (a-ha!) vardır.
|
||||
|
||||
[Adam Stacoviak ve Jerod Santo ile Changelog Podcast'inde][thechangelog](uyuyor,
|
||||
[Adam Stacoviak ve Jerod Santo ile Changelog Podcast'inde][thechangelog] (uyuyor,
|
||||
değil mi?) neden geliştiricilerin ve katılımcıların umrunda olması gerektiğini ve
|
||||
bu projenin arkasındaki motivasyonu konuştuk. Eğer vaktiniz varsa (1:06) iyi bir
|
||||
söyleşi oldu.
|
||||
@ -36,20 +36,20 @@ version: 0.3.0
|
||||
|
||||
İyi bir değişiklik kaydı şu prensiplere bağlıdır:
|
||||
|
||||
- İnsanlar için yapılmıştır, makineler için değil, yani okunurluğu kritik.
|
||||
- Kolayca bölümler arası bağlantı kurulabilmeli (bu yüzden yalın metin yerine markdown).
|
||||
- Her sürüm için bir alt bölüm.
|
||||
- Dağıtımları tersine tarih sırası ile listeleyin (en yeni en üstte).
|
||||
- Tüm tarihleri `YYYY-AA-GG` biçiminde yazın. (Örneğin `2 Haziran 2012` için `2012-06-02`.) Uluslararasıdır, [anlamlıdır](http://xkcd.com/1179/), ve lisan bağımsızdır.
|
||||
- [Anlamsal sürümlemeyi][semver] destekleyip desteklemediğini özellikle belirtin.
|
||||
- İnsanlar için yapılmıştır, makineler için değil, yani okunabilirliği kritiktir.
|
||||
- Kolayca bölümler arası bağlantı kurulabilmelidir. (Bu yüzden yalın metin yerine markdown)
|
||||
- Her sürüm için bir alt bölüm içermelidir.
|
||||
- Dağıtımları tersine tarih sırası ile listemelidir. (En yeni en üstte)
|
||||
- Tüm tarihler `YYYY-AA-GG` biçiminde olmalıdır. (Örneğin `2 Haziran 2012` için `2012-06-02`) Uluslararasıdır, [anlamlıdır](http://xkcd.com/1179/), ve lisan bağımsızdır.
|
||||
- [Anlamsal sürümleme][semver]nin desteklenip desteklenmediğini özellikle belirtilmelidir.
|
||||
- Her sürümde olması gerekenler:
|
||||
- Üstteki biçimde dağıtım tarihi.
|
||||
- Projeye etkileri bakımından değişiklikleri gruplayın, şöyle ki:
|
||||
- `Eklendi`: yeni özellikler için.
|
||||
- `Değişti`: var olan beceriler değiştiyse.
|
||||
- `Rafa kalktı`: gelecekte yok olacak var olan beceriler.
|
||||
- `Kaldırıldı`: bu sürümde kaldırılan, daha önce rafa kaldırılmış olan beceriler.
|
||||
- `Düzeltildi`: ayıklanmış hatalar için.
|
||||
- Projeye etkileri bakımından değişikliklerin gruplanması, şöyle ki:
|
||||
- `Eklendi`: yeni özellikler için,
|
||||
- `Değişti`: var olan beceriler değiştiyse,
|
||||
- `Rafa kalktı`: gelecekte yok olacak var olan beceriler,
|
||||
- `Kaldırıldı`: bu sürümde kaldırılan, daha önce rafa kaldırılmış olan beceriler,
|
||||
- `Düzeltildi`: ayıklanmış hatalar,
|
||||
- `Güvenlik`: açıkları kapatabilmeleri için kullanıcıları bilgilendirin.
|
||||
|
||||
### Gerekli çabayı nasıl en aza indirebilirim?
|
||||
@ -65,7 +65,7 @@ version: 0.3.0
|
||||
Peki… Gelelim sadede.
|
||||
|
||||
- **Commit kayıtlarının farkını yüklemek.** Sakın bunu yapmayın, kimseye yardım etmiyorsunuz.
|
||||
- **Rafa kalkanları ön plana çıkarmamak.** Kullanıcılar bir sürümden diğerine
|
||||
- **Rafa kaldırılanları ön plana çıkarmamak.** Kullanıcılar için bir sürümden diğerine
|
||||
yükseltme yaptıklarında neyin bozulabileceği apaçık ortada olmalı.
|
||||
- **Bölgesel biçimlenmiş tarihler.** ABD'de insanlar ay bilgisini önce kullanıyor
|
||||
("06-02-2012" demek 2 Haziran 2012 demek yani, ki tamamen *saçma*), diğer taraftan
|
||||
@ -101,12 +101,12 @@ version: 0.3.0
|
||||
Tam bir karmaşa. Tüm bu isimler insanların bu dosyayı bulmasını zorlaştırıyor.
|
||||
|
||||
### Neden `git log` farkları kullanılmasın?
|
||||
Çünkü kayıt farkları bir sürü gürültü içerir - doğal olarak. Mükemmel insanlar
|
||||
Çünkü kayıt farkları bir sürü parazit içerir - doğal olarak. Mükemmel insanlar
|
||||
tarafından yürütülen, hiç yazım hatasının yapılmadığı, dosyaların gönderilmesinin
|
||||
hiç unutulmadığı, refaktör yapılmasının atlanmadığı varsayımsal bir projede bile
|
||||
uygun bir değişiklik kaydı oluşmayacaktır. Dosyaları repoya göndermenin amacı
|
||||
hiç unutulmadığı, refaktör yapılmasının atlanmadığı varsayımsal bir projede bile,
|
||||
uygun bir değişiklik kaydı oluşmayacaktır. Dosyaları repoya göndermenin amacı,
|
||||
atomik seviyede kodun bir durumdan diğerine geçişinin sağlanmasıdır. Değişiklik
|
||||
kayıtları ise bu durumlar arasında, önem arz eden değişiklikleri belgelemeyi
|
||||
kayıtları ise, bu durumlar arasında önem arz eden değişiklikleri belgelemeyi
|
||||
amaçlıyor.
|
||||
|
||||
İyi yorumlar ve kodun kendisi arasındaki fark,
|
||||
@ -128,7 +128,7 @@ version: 0.3.0
|
||||
Büyük harfle isimlendirme (eski işletim sistemlerinde dosyaların tepede
|
||||
gözükmelerini sağlardı) dikkat çekmek için. Proje hakkında önemli meta verileri
|
||||
içerdikleri için, kullanmak ya da katkıda bulunmak isteyen herkesin işine
|
||||
yarar, tıpkı [açık kaynaklı proje rozeleri][shields] gibi.
|
||||
yarar, tıpkı [açık kaynaklı proje rozetleri][shields] gibi.
|
||||
|
||||
"Değişiklik kaydı"ndan bahsettiğim zamanlar bu dosyanın işlevinden bahsediyorum:
|
||||
Değişiklikleri kaydetmek.
|
||||
@ -142,7 +142,7 @@ version: 0.3.0
|
||||
|
||||
`[GERİ ÇEKİLDİ]` etiketi belirli bir sebepten büyük harf. İnsanların bunu fark
|
||||
etmeleri çok önemli. Ayrıca köşeli parantezler ile çevrelenmiş olması
|
||||
programatik olarak da ayrıştırılabilmeine olanak sağlıyor.
|
||||
programatik olarak da ayrıştırılabilmesine olanak sağlıyor.
|
||||
|
||||
### Değişiklik kayıtlarınızı tekrar yazmalı mısınız?
|
||||
Tabii ki. Her zaman değişiklik kayıtlarını geliştirmek için iyi sebepler vardır.
|
||||
|
||||
@ -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]团队制作），可以解析
|
||||
好多种（但绝对不是全部）开源库的更新日志。
|
||||
|
||||
@ -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]。
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user