diff --git a/CHANGELOG.md b/CHANGELOG.md index 6f13023..41a6817 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/config.rb b/config.rb index 4ac42e0..5f3624b 100644 --- a/config.rb +++ b/config.rb @@ -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" => "简体中文", 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/pt-BR/0.3.0/index.html.haml b/source/pt-BR/0.3.0/index.html.haml index c68f4a4..e03841a 100644 --- a/source/pt-BR/0.3.0/index.html.haml +++ b/source/pt-BR/0.3.0/index.html.haml @@ -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 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/tr-TR/0.3.0/index.html.haml b/source/tr-TR/0.3.0/index.html.haml index a08e66b..2ac8f80 100644 --- a/source/tr-TR/0.3.0/index.html.haml +++ b/source/tr-TR/0.3.0/index.html.haml @@ -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. 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]。