diff --git a/CHANGELOG.md b/CHANGELOG.md index b3257eb..41a6817 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/config.rb b/config.rb index 41a75da..5f3624b 100644 --- a/config.rb +++ b/config.rb @@ -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, diff --git a/source/cs/0.3.0/index.html.haml b/source/cs/0.3.0/index.html.haml new file mode 100644 index 0000000..208f7ac --- /dev/null +++ b/source/cs/0.3.0/index.html.haml @@ -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/ diff --git a/source/de/0.3.0/index.html.haml b/source/de/0.3.0/index.html.haml index ed7e8e9..c0d27af 100644 --- a/source/de/0.3.0/index.html.haml +++ b/source/de/0.3.0/index.html.haml @@ -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. diff --git a/source/fr/0.3.0/index.html.haml b/source/fr/0.3.0/index.html.haml new file mode 100644 index 0000000..87abdd6 --- /dev/null +++ b/source/fr/0.3.0/index.html.haml @@ -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/ diff --git a/source/it-IT/0.3.0/index.html.haml b/source/it-IT/0.3.0/index.html.haml new file mode 100644 index 0000000..543a6fe --- /dev/null +++ b/source/it-IT/0.3.0/index.html.haml @@ -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/ diff --git a/source/layouts/layout.html.haml b/source/layouts/layout.html.haml index 5afea05..e6ddcab 100644 --- a/source/layouts/layout.html.haml +++ b/source/layouts/layout.html.haml @@ -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 diff --git a/source/pt-BR/0.3.0/index.html.haml b/source/pt-BR/0.3.0/index.html.haml index 4d981a5..4a8207f 100644 --- a/source/pt-BR/0.3.0/index.html.haml +++ b/source/pt-BR/0.3.0/index.html.haml @@ -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? diff --git a/source/sl/0.3.0/index.html.haml b/source/sl/0.3.0/index.html.haml new file mode 100644 index 0000000..73b11c3 --- /dev/null +++ b/source/sl/0.3.0/index.html.haml @@ -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/ diff --git a/source/sv/0.3.0/index.html.haml b/source/sv/0.3.0/index.html.haml index 7bc0121..d5004f6 100644 --- a/source/sv/0.3.0/index.html.haml +++ b/source/sv/0.3.0/index.html.haml @@ -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 diff --git a/source/zh-CN/0.3.0/index.html.haml b/source/zh-CN/0.3.0/index.html.haml index 1837edf..910bf87 100644 --- a/source/zh-CN/0.3.0/index.html.haml +++ b/source/zh-CN/0.3.0/index.html.haml @@ -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]团队制作），可以解析 好多种（但绝对不是全部）开源库的更新日志。 diff --git a/source/zh-TW/0.3.0/index.html.haml b/source/zh-TW/0.3.0/index.html.haml index 564d883..2bf8a50 100644 --- a/source/zh-TW/0.3.0/index.html.haml +++ b/source/zh-TW/0.3.0/index.html.haml @@ -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]。