diff --git a/CHANGELOG.md b/CHANGELOG.md index 2477c97..cac12d1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,18 +1,23 @@ # Changelog All notable changes to this project will be documented in this file. -The format is based on [Keep a Changelog](http://keepachangelog.com/) -and this project adheres to [Semantic Versioning](http://semver.org/). +The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) +and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). ## [Unreleased] + +## [1.0.0] - 2017-06-20 ### Added +- New visual identity by @tylerfortune8. +- Version navigation. +- Links to latest released version in previous versions. - "Why keep a changelog?" section. - "Who needs a changelog?" section. - "How do I make a changelog?" section. - "Frequently Asked Questions" section. - New "Guiding Principles" sub-section to "How do I make a changelog?". - Simplified and Traditional Chinese translations from @tianshuo. -- German translation from @mpbzh. +- German translation from @mpbzh & @Art4. - Italian translation from @roalz. - Swedish translation from @magol. - Turkish translation from @karalamalar. @@ -124,7 +129,8 @@ notable changes. - Good examples and basic guidelines, including proper date formatting. - Counter-examples: "What makes unicorns cry?" -[Unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...HEAD +[Unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...HEAD +[1.0.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0 [0.3.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.2.0...v0.3.0 [0.2.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.2.0 [0.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.8...v0.1.0 diff --git a/README.md b/README.md index 29980b8..d841437 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Keep a Changelog -[![version][version-badge]][CHANGELOG] [![license][license-badge]][LICENSE] +[![version][version-badge]][CHANGELOG] [![license][license-badge]][LICENSE] Don’t let your friends dump git logs into changelogs™ @@ -20,22 +20,23 @@ This repository generates http://keepachangelog.com/. - `bundle exec middleman` starts the local development server at http://localhost:4567 ### Deployment -- `rake publish` builds and pushes to the `gh-pages` branch +- `bundle exec rake publish` builds and pushes to the `gh-pages` branch ### Translations -Create a new directory in [`source/`][source] named after the ISO 639-1 code -for the language you wish to translate Keep a Changelog to. For example, +Create a new directory in [`source/`][source] named after the ISO 639-1 code +for the language you wish to translate Keep a Changelog to. For example, assuming you want to translate to French Canadian: + - create the `source/fr-CA` directory. -- duplicate the `source/en-US/index.html.haml` file in `source/fr-CA`. -- edit `source/fr-CA/index.html.haml` until your translation is ready. +- duplicate the `source/en/1.0.0/index.html.haml` file in `source/fr-CA`. +- edit `source/fr-CA/1.0.0/index.html.haml` until your translation is ready. - commit your changes to your own [fork][fork] - submit a [Pull Request][pull-request] with your changes -It may take some time to review your submitted Pull Request. Try to involve a +It may take some time to review your submitted Pull Request. Try to involve a few native speakers of the language you're translating to in the Pull Request -comments. They'll help review your translation for simple mistakes and give us +comments. They'll help review your translation for simple mistakes and give us a better idea of whether your translation is accurate. Thank you for your help improving software one changelog at a time! @@ -47,5 +48,5 @@ Thank you for your help improving software one changelog at a time! [source]: source/ [pull-request]: https://help.github.com/articles/creating-a-pull-request/ [fork]: https://help.github.com/articles/fork-a-repo/ -[version-badge]: https://img.shields.io/badge/version-0.3.0-blue.svg +[version-badge]: https://img.shields.io/badge/version-1.0.0-blue.svg [license-badge]: https://img.shields.io/badge/license-MIT-blue.svg diff --git a/source/assets/images/favicon.ico b/source/assets/images/favicon.ico new file mode 100644 index 0000000..7a0f597 Binary files /dev/null and b/source/assets/images/favicon.ico differ diff --git a/source/assets/images/logo.png b/source/assets/images/logo.png new file mode 100644 index 0000000..ec0efe8 Binary files /dev/null and b/source/assets/images/logo.png differ diff --git a/source/assets/images/logo.svg b/source/assets/images/logo.svg new file mode 100644 index 0000000..4bc1b76 --- /dev/null +++ b/source/assets/images/logo.svg @@ -0,0 +1 @@ +Artboard 1 \ No newline at end of file diff --git a/source/de/1.0.0/index.html.haml b/source/de/1.0.0/index.html.haml new file mode 100644 index 0000000..6ee1485 --- /dev/null +++ b/source/de/1.0.0/index.html.haml @@ -0,0 +1,319 @@ +--- +description: Keep a Changelog +title: Keep a Changelog +language: de +version: 1.0.0 +--- + +- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.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/" +- iso = "http://www.iso.org/iso/home/standards/iso8601.htm" +- ghr = "https://help.github.com/articles/creating-releases/" + +.header + .title + %h1 Führe ein CHANGELOG + %h2 Lass Deine Freunde nicht CHANGELOGs mit git logs füllen. + + = link_to changelog do + Version + %strong= current_page.metadata[:page][:version] + + %pre.changelog= File.read("CHANGELOG.md") + +.answers + %h3#what + %a.anchor{ href: "#what", aria_hidden: "true" } + Was ist ein Changelog? + + %p + Ein Changelog ist eine Datei, die eine handgepflegte, chronologisch sortierte + Liste aller erheblichen Änderungen enthält, die zwischen einzelnen Veröffentlichungen + (oder Versionen) des Projekts umgesetzt wurden. + + %h3#why + %a.anchor{ href: "#why", aria_hidden: "true" } + Was ist der Zweck eines Changelogs? + + %p + Ein Changelog soll es Benutzern und Entwicklern einfacher machen, gerade die + beachtenswerten Änderungen, die zwischen Veröffentlichungen (oder Versionen) + des Projekts gemacht wurden, zu sehen. + + %h3#who + %a.anchor{ href: "#who", aria_hidden: "true" } + Wer braucht schon ein Changelog? + + %p + Menschen brauchen es. Seien es Konsumenten oder Entwickler, die Endnutzer der Software + sind Menschen, die es interessiert, was in der Software passiert. Wenn sich die Software ändert, + dann wollen diese Menschen wissen, wie und warum sie sich ändert. + +.good-practices + %h3#how + %a.anchor{ href: "#how", aria_hidden: "true" } + Wie erstelle ich einen guten Changelog? + + %h4#principles + %a.anchor{ href: "#principles", aria_hidden: "true" } + Grundlegende Prinzipien + + %ul + %li + Changelogs werden für Menschen geschrieben, nicht für Maschinen. + %li + Für jede einzelne Version sollte es einen Eintrag geben. + %li + Änderungen der selben Art sollten in Bereiche gruppiert werden. + %li + Versionen und Bereiche sollten verlinkt werden können. + %li + Die neuste Version kommt als erstes. + %li + Das Release-Datum jeder Version muss angegeben sein. + %li + Gib an, ob du dich an die #{link_to "Semantische Versionierung", semver} hältst. + + %a.anchor{ href: "#types", aria_hidden: "true" } + %h4#types Arten von Änderungen + + %ul + %li + %code Added + für neue Features. + %li + %code Changed + für Änderungen an der bestehenden Funktionalität. + %li + %code Deprecated + für Features, die in zukünftigen Versionen entfernt werden. + %li + %code Removed + für Deprecated-Features, die in dieser Version entfernt wurden. + %li + %code Fixed + für alle Bug-Fixes. + %li + %code Security + um Benutzer im Fall von geschlossenen Sicherheitslücken zu einer Aktualisierung aufzufordern. + +.effort + + %h3#effort + %a.anchor{ href: "#effort", aria_hidden: "true" } + Wie kann ich den Aufwand der Changelog-Pflege so klein wie möglich halten? + + %p + Habe immer einen Unreleased-Abschnitt über der neusten Version, + um zukünftige Änderungen im Auge zu behalten. + + %p Dies hat zwei Vorteile: + + %ul + %li + Menschen können sehen, welche Änderungen sie mit dem nächsten Release zu erwarten haben. + %li + Wenn der Zeitpunkt für den Release gekommen ist, kannst du den Inhalt des + Unreleased-Abschnitts in den neuen Release-Abschnitt verschieben. + +.bad-practices + %h3#bad-practices + %a.anchor{ href: "#bad-practices", aria_hidden: "true" } + Kann man beim Changelog etwas falsch machen? + + %p Ja. Hier sind einige Dinge, die eher unbrauchbar sind. + + + %h4#log-diffs + %a.anchor{ href: "#log-diffs", aria_hidden: "true" } + Einen Diff von Commit-Logs ausgeben + + %p + Commit-Logs in einem Changelog sind eine schlechte Idee: Sie beinhalten lauter + überflüssige Dinge, wie Merge-Commit, Commits mit schlechten Bezeichnungen, + Änderungen an der Dokumentation, etc. + + %p + Der Sinn eines Commits ist die Entwicklung des Source Code zu dokumentieren. + Manche Projekte haben saubere Commits, andere nicht. + + %p + Der Sinn eines Changelog-Eintrags ist die Dokumentation der merkbaren + Unterschiede, die meist über mehrere Commits hinweg entstanden sind, dem + Endnutzer klar und deutlich zu kommunizieren. + + + %h4#ignoring-deprecations + %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } + Features ohne Deprecation-Warnung entfernen + + %p + Wenn der Endnutzer auf eine neue Version upgradet, sollte ihm unmissverständlich + klar gemacht werden, wenn etwas kaputt gehen wird. Es sollte immer möglich sein, + zu einer Version zu upgraden, die die zu entfernenden Features auflistet, um so + in seinem Source Code auf diese Features zu verzichten. Anschließend sollte man + auf eine Version upgraden können, in der die Features entfernt wurden. + + %p + Auch wenn du sonst nichts geändert hast, liste trotzdem alle veralteten und + entfernten Features, sowie jede funktionsgefährdende Änderung in deinem Changelog auf. + + + %h4#confusing-dates + %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } + Verwirrende Datumsformate + + %p + In den USA setzen die Menschen den Monat an den Anfang eines Datums + (06-02-2012 für den 2. Juni 2012), wohingegen viele Menschen + im Rest der Welt ein roboterhaft aussehendes 2 June 2012 + schreiben, aber es völlig unterschiedlich aussprechen. 2012-06-02 + folgt der Logik vom größten zum kleinsten Wert, kann nicht mit anderen Formaten + verwechselt werden und ist ein #{link_to "ISO Standard", iso}. Deshalb + ist es das empfohlene Datumsformat in Changelogs. + + %aside + Es gibt sicher noch mehr. Hilf mir alle schlechten Tipps zu sammeln, indem du + = link_to "ein Issue eröffnest", "#issues" + oder einen Pull-Request erstellst. + +.frequently-asked-questions + %h3#frequently-asked-questions + %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" } + Häufig gestellte Fragen + + %h4#standard + %a.anchor{ href: "#standard", aria_hidden: "true" } + Gibt es ein standardisiertes Changelog-Format? + + %p + Leider nicht. Es gibt zwar den GNU Changelog Styleguide oder den + zwei Absätze langen GNU NEWS-Datei "Leitfaden". Beide sind aber + unzureichend. + + %p + Dieses Projekt versucht + = link_to "eine bessere Changelog Konvention zu sein.", changelog + Dazu beobachten wir bewährte Praktiken aus der Open Source Community + und tragen sie zusammen. + + %p + Gesunde Kritik, Diskussionen und Verbesserungsvorschläge + = link_to "sind herzlich willkommen.", issues + + + %h4#filename + %a.anchor{ href: "#filename", aria_hidden: "true" } + Wie sollte die Changelog-Datei benannt sein? + + %p + Nenne sie CHANGELOG.md. Manche Projekte verwenden auch + HISTORY, NEWS oder RELEASES. + + %p + Man könnte zwar meinen, dass der Name der Changelog-Datei keine große + Bedeutung hat, aber warum sollte man es den Endnutzern nicht einfach machen, + die Änderungen des Projekts zu finden, indem man einen einheitlichen Namen + verwendet? + + + %h4#github-releases + %a.anchor{ href: "#github-releases", aria_hidden: "true" } + Was ist mit GitHub Releases? + + %p + Prinzipiell sind #{link_to "GitHub Releases", ghr} eine gute Sache. + Sie können dazu benutzt werden, um einfache Git Tags (zum Beispiel einen + Tag namens v1.0.0) mit vielen Hinweisen zum Release + auszustatten, indem man sie manuell bearbeitet, oder die Änderungen in eine + Git Tag Nachricht schreibt, wo sie durch GitHub automatisch in die + Release-Notizen gesetzt werden. + + %p + Leider lassen sich GitHub Releases aber nicht so einfach exportieren + und sind nur über GitHub selber zu lesen. Man kann sie auch so gestalten, + dass sie dem Keep a Changelog Format sehr ähnlich sehen, aber dazu betreibt + man in der Regel einen größeren Aufwand. + + %p + Die derzeitige Version der GitHub Releases sind außerdem nicht leicht + durch die Endnutzer zu finden, ganz im Gegenteil zu den typischerweise + großgeschriebenen Dateien (README, CONTRIBUTING, etc.). + Ein weiterer kleiner Nachteil ist, dass das Web Interface zurzeit keinen Link + anbietet, um die Commits zwischen einzelnen Releases miteinander zu vergleichen. + + + %h4#automatic + %a.anchor{ href: "#automatic", aria_hidden: "true" } + Können Changelogs automatisiert ausgelesen werden? + + %p + Es ist schwierig, weil Menschen meist unterschiedliche Formate und + Dateinamen verwenden. + + %p + #{link_to "Vandamme", vandamme} ist ein Ruby gem erstellt vom + #{link_to "Gemnasium", gemnasium} Team, das viele (aber nicht alle) + Changelogs von Open-Source-Projekten einlesen kann. + + + %h4#yanked + %a.anchor{ href: "#yanked", aria_hidden: "true" } + Wie sieht es mit zurückgezogenen Releases aus? + + %p + Sogenannte "Yanked Releases" sind Versionen, welche wegen schwerwiegenden + Bugs oder Sicherheitsproblemen zurückgezogen werden mussten. Häufig kommen + diese im Changelog gar nicht vor, aber das sollten sie. So solltest Du diese + Versionen darstellen: + + %p ## 0.0.5 - 2014-12-13 [YANKED] + + %p + Der [YANKED] ist nicht ohne Grund großgeschrieben. Es ist wichtig, + dass sie von Menschen bemerkt werden. Weil er von eckigen Klammern umgeben ist, + kann man sie außerdem einfacher automatisiert einlesen. + + + %h4#rewrite + %a.anchor{ href: "#rewrite", aria_hidden: "true" } + Sollte ich ein Changelog je umschreiben? + + %p + Klar. Es gibt immer gute Gründe, ein Changelog zu verbessern. Ich öffne + regelmässig Pull Requests, um Open-Source-Projekten mit schlecht gewarteten + Changelogs fehlende Releases hinzuzufügen. + + %p + 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. + + + %h4#contribute + %a.anchor{ href: "#contribute", aria_hidden: "true" } + Wie kann ich mithelfen? + + %p + Dieses Dokument ist nicht die Wahrheit. Es ist meine wohl überlegte Meinung, + zusammen mit von mir zusammengetragenen Informationen und Beispielen. + + %p + So möchte ich erreichen, dass die Community einen Konsens findet. Ich glaube, dass + die Disskussion genauso wichtig ist wie das Endergebnis. + + %p + Also bitte #{link_to "bring dich ein", gh}. + +.press + %h3 Gespräche + %p + Ich habe im #{link_to "The Changelog podcast", thechangelog} darüber gesprochen, + warum sich Entwickler und Mitwirkende eines Projekts um ein Changelog kümmern sollten, + sowie meine Motivationen hinter diesem Projekt erklärt. diff --git a/source/en/1.0.0/index.html.haml b/source/en/1.0.0/index.html.haml index 5536999..08f467d 100644 --- a/source/en/1.0.0/index.html.haml +++ b/source/en/1.0.0/index.html.haml @@ -51,7 +51,7 @@ version: 1.0.0 %p People do. Whether consumers or developers, the end users of - software are human beings who care about what's in the sofware. When + software are human beings who care about what's in the software. When the software changes, people want to know why and how. .good-practices diff --git a/source/fr/1.0.0/index.html.haml b/source/fr/1.0.0/index.html.haml index c90ff33..c5b3a62 100644 --- a/source/fr/1.0.0/index.html.haml +++ b/source/fr/1.0.0/index.html.haml @@ -33,7 +33,7 @@ version: 1.0.0 Qu'est-ce qu'un changelog ? %p - Un changelog (journal de modifications) est un fichier qui contient + Un changelog (journal des modifications) est un fichier qui contient une liste triée chronologiquement des changements notables pour chaque version d’un projet @@ -42,8 +42,8 @@ version: 1.0.0 Pourquoi tenir un changelog ? %p - Pour permettre aux utilisateurs et contributeurs de voir précisement - quel changements notables ont été faits entre chaque publication + Pour permettre aux utilisateurs et contributeurs de voir précisément + quels changements notables ont été faits entre chaque publication (ou version) d'un projet. %h3#who @@ -51,10 +51,10 @@ version: 1.0.0 Qui a besoin d'un changelog ? %p - Tout le monde. Qu'ils soient consomateurs ou developeurs, les + Tout le monde. Qu'ils soient consommateurs ou développeurs, les utilisateurs de logiciels sont des êtres humains qui se soucient de connaître le contenu des logiciels qu'ils utilisent. Quand un - logiciel change, ces même personnes veulent savoir comment et pourquoi. + logiciel change, ces mêmes personnes veulent savoir comment et pourquoi. .good-practices %h3#how @@ -69,7 +69,7 @@ version: 1.0.0 %li Les changelogs sont pour les êtres humains, pas les machines. %li - Il doit il y avoir une section pour chaque version. + Il doit y avoir une section pour chaque version. %li Les changements similaires doivent être groupés. %li @@ -102,7 +102,7 @@ version: 1.0.0 pour les corrections de bugs. %li %code Security - en cas de vulnerabilités. + en cas de vulnérabilités. .effort @@ -114,11 +114,11 @@ version: 1.0.0 Gardez une section Unreleased en haut du fichier afin de lister tous les changements qui n'ont pas encore été publiés. - %p Cela rempli deux objectifs: + %p Cela permet deux choses: %ul %li - Les gens peuvent voir les changements auxquels ils peuvent s’attendrent + Les gens peuvent voir les changements auxquels ils peuvent s’attendre dans les prochaines publications. %li Au moment de la publication, vous pouvez déplacer les changements listés @@ -134,12 +134,12 @@ version: 1.0.0 %h4#log-diffs %a.anchor{ href: "#log-diffs", aria_hidden: "true" } - Diffs de journaux git + Diffs de journaux gits %p - Utiliser des diffs de journaux git en tant que changelogs est une mauvaise - idée: ils sont remplis de bruit. Les journaux git sont remplis de choses - comme des commits de merge, des commits avec des titres obscures, des + Utiliser des diffs de journaux gits en tant que changelogs est une mauvaise + idée: ils sont remplis de bruit. Les journaux gits sont remplis de choses + comme des commits de merge, des commits avec des titres obscurs, des changements concernant la documentation, etc. %p @@ -147,9 +147,9 @@ version: 1.0.0 source. Certains projets nettoient leurs commits, d'autres non. %p - Le but d'une section de changelog est de documenter la difference notable - entre deux versions, souvent à travers de multiples commits, afin de la - communiquer clairement aux utilisateurs. + Le but d'une section de changelog est de documenter les différences + notables entre deux versions, souvent à travers de multiples + commits, afin de les communiquer clairement aux utilisateurs. %h4#ignoring-deprecations %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } @@ -157,7 +157,7 @@ version: 1.0.0 %p Lorsque l'on passe d'une version d'un logiciel à une autre, il devrait être - très clair si quelque chose peut ne pas fonctionner. Il devrait être + très clair si quelque chose peut ne plus fonctionner. Il devrait être possible de mettre à jour vers un version qui offre une liste des fonctionnalités dépréciées, de retirer ce qui est déprécié, puis de mettre à jour vers la version où les dépréciations deviennent des suppressions de @@ -180,10 +180,10 @@ version: 1.0.0 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 #{link_to "standard ISO", iso}. C'est pour cela que ce format de date - est recommandé pour les change logs. + est recommandé pour les changelogs. %aside - Il y en a d’autres. Aidez-moi à collecter ces anti-patrons en + Il y en a d’autres. Aidez-moi à collecter ces antipatrons en #{link_to "ouvrant une issue", "#issues"} ou une pull request. .frequently-asked-questions @@ -198,7 +198,7 @@ version: 1.0.0 %p Pas vraiment. Il y a le guide de style GNU pour les changelogs, ou les instructions GNU de deux paragraphes pour les fichiers NEWS. Ces deux - resources sont inappropriées et insuffisantes. + ressources sont inappropriées et insuffisantes. %p Ce projet vise à devenir @@ -213,16 +213,16 @@ version: 1.0.0 %h4#filename %a.anchor{ href: "#filename", aria_hidden: "true" } - Comment doit-être nommé le fichier de change log ? + Comment doit-être nommé le fichier de changelog ? %p - Nommez le CHANGELOG.md. Certains projects utilisent + Nommez-le CHANGELOG.md. Certains projets utilisent HISTORY, NEWS ou RELEASES. %p Même s'il est facile d'imaginer que le nom d'un fichier de changelog n'a - pas grant interêt, pourquoi rendre la tâche difficile que nécessaire pour - les utilisateurs qui cherchent à trouver les changements notables de votre + pas grand intérêt, pourquoi rendre la tâche plus difficile que nécessaire + aux utilisateurs qui cherchent à trouver les changements notables de votre projet ? %h4#github-releases @@ -238,19 +238,19 @@ version: 1.0.0 %p GitHub Releases crée un changelog non-portable qui n'est visible par les - utilisateurs qu'à l'interieur du context de GitHub. Il est possible de + utilisateurs qu'à l'intérieur du contexte de GitHub. Il est possible de suivre le même format que Keep a Changelog, mais c'est plus difficile. %p La version actuelle de GitHub Releases est également difficile à découvrir pour les utilisateurs, contrairement aux fichiers en majuscules typiques - (README, CONTRIBUTING, etc.). Un autre soucis - mineur est que l'interface ne permet pas actuellement d'offrir des liens - vers les journaux git entre chaque publication. + (README, CONTRIBUTING, etc.). Un autre souci + mineur est que l'interface n'offre actuellement pas de lien vers les + journaux gits entre chaque publication. %h4#automatic %a.anchor{ href: "#automatic", aria_hidden: "true" } - Les change logs peuvent-ils être parsés automatiquement ? + Les changelogs peuvent-ils être parsés automatiquement ? %p C'est difficile, parce que les gens suivent des formats et utilisent des noms @@ -258,7 +258,7 @@ version: 1.0.0 %p #{link_to "Vandamme", vandamme} est une Ruby gem créée par l'équipe - #{link_to "Gemnasium", gemnasium} qui parse les change logs de + #{link_to "Gemnasium", gemnasium} qui parse les changelogs de beaucoup (mais pas tous) de projets open source. diff --git a/source/layouts/layout.html.haml b/source/layouts/layout.html.haml index bce9730..91b2244 100644 --- a/source/layouts/layout.html.haml +++ b/source/layouts/layout.html.haml @@ -20,10 +20,12 @@ %meta{ property: 'og:type', content: 'article' } %meta{ property: 'og:url', content: path_to_url(current_page.url) } %meta{ property: 'og:description', content: current_page.data.description } + %meta{ property: 'og:image', content: image_path("logo.png") } = yield_content :og -# Icons + %link{ rel: "shortcut icon", type: "image/x-icon", href: image_path("favicon.ico") } %link{ rel: 'canonical', href: path_to_url(current_page.url) } %title= current_page.data.title diff --git a/source/sv/1.0.0/index.html.haml b/source/sv/1.0.0/index.html.haml index dad19c9..075736b 100644 --- a/source/sv/1.0.0/index.html.haml +++ b/source/sv/1.0.0/index.html.haml @@ -64,7 +64,7 @@ version: 1.0.0 %ul %li - Ändringsloggar är för människor, inte maskiner. + Ändringsloggar är för människor, inte maskiner. %li Det bör finnas en post för varje enskild version. %li @@ -117,7 +117,7 @@ version: 1.0.0 %li Folk kan se vilka ändringar de kan förvänta sig i kommande utgåvor %li - Vid lansering behöver du bara flytta innehållet i sektionen + Vid lansering behöver du bara flytta innehållet i sektionen Unreleased till en ny versionspost. .bad-practices @@ -132,8 +132,8 @@ version: 1.0.0 Diffar från incheckningsloggen. %p - Det är en dålig idé att använda incheckningsloggen som ändringslogg: - de är fulla av brus. Saker så som merge-incheckningar, incheckningar med + Det är en dålig idé att använda incheckningsloggen som ändringslogg: + de är fulla av brus. Saker så som merge-incheckningar, incheckningar med otydliga titlar, dokumentationsförändringar etc. %p @@ -150,14 +150,14 @@ version: 1.0.0 Ignorera föråldrad funktionalitet (deprecations) %p - När användare uppgraderar från en version till en annan, ska det vara + När användare uppgraderar från en version till en annan, ska det vara smärtsamt uppenbart när något förväntas gå sönder. Den bör vara möjligt att uppgradera till en version som listar föråldrad funktionalitet, ta - bort dessa beroenden i sitt program, och sedan uppgradera till en version + bort dessa beroenden i sitt program, och sedan uppgradera till en version där den föråldrade funktionaliteten är borttagen. %p - Om du inte gör något annat, lista åtminstone föråldrad och borttagen + Om du inte gör något annat, lista åtminstone föråldrad och borttagen funktionalitet samt förstörande förändringar i din ändringslogg. %h4#confusing-dates @@ -165,11 +165,11 @@ version: 1.0.0 Förvillande datum %p - I USA lägger folk månaden först (06-02-2012 för 2:a juni 2012), - medan många andra runt om i världen skriver 2 June 2012 men - uttalar det annorlunda. 2012-06-02 fungerar logiskt från störst - till minst, överlappar inte på något tvetydligt sätt med andra datumformat, - och är en #{link_to "ISO-standard", iso}. Dessutom är det rekommenderat + I USA lägger folk månaden först (06-02-2012 för 2:a juni 2012), + medan många andra runt om i världen skriver 2 June 2012 men + uttalar det annorlunda. 2012-06-02 fungerar logiskt från störst + till minst, överlappar inte på något tvetydligt sätt med andra datumformat, + och är en #{link_to "ISO-standard", iso}. Dessutom är det rekommenderat datumformat för ändringsloggar. %aside @@ -187,9 +187,9 @@ version: 1.0.0 Finns det ett standardformat på ändringsloggar? %p - Inte riktigt. GNU:s stilguide för ändringsloggar och den två stycke - långa GNU NEWS-filen med riktlinjer finns. Båda är bristfälliga och - otillräckliga. + Inte riktigt. GNU:s stilguide för ändringsloggar och den två stycke + långa GNU NEWS-filen med riktlinjer finns. Båda är bristfälliga och + otillräckliga. %p Detta projekt har som mål att bli @@ -219,20 +219,20 @@ version: 1.0.0 %p Det är ett fantasiskt initiativ. #{link_to "Releases", ghr} kan användas - för att göra enkla git-taggar (t.ex. en tagg kallad v1.0.0) - till formaterade versionsanteckningar genom att manuellt lägga till - versionsanteckningar eller så kan den hämta meddelandena i kommenterade + för att göra enkla git-taggar (t.ex. en tagg kallad v1.0.0) + till formaterade versionsanteckningar genom att manuellt lägga till + versionsanteckningar eller så kan den hämta meddelandena i kommenterade git-taggar och omvandla dessa till versionsanteckningar. %p GitHub Releases skapar en icke porterbar ändringslogg som enbart kan visas för användare på GitHub. Det är möjligt att formatera det ungefär som på Håll en ändringslogg-formatet, men det tendera att bli lite mer invecklat. - + %p Nuvarande version av GitHub releases är möjligtvis också lite svår att - hitta för slutanvändare, till skillnad från filer med normalt stora - bokstäver (README, CONTRIBUTING, etc.). + hitta för slutanvändare, till skillnad från filer med normalt stora + bokstäver (README, CONTRIBUTING, etc.). Ett annat bekymmer är att användargränssnittet för närvarande inte erbjuder länkar till incheckningsloggar mellan olika versioner. @@ -244,10 +244,10 @@ version: 1.0.0 Det är svårt då människor följer vitt olika format och filnamn. %p - #{link_to "Vandamme", vandamme} är en Ruby gem skapad av gruppen + #{link_to "Vandamme", vandamme} är en Ruby gem skapad av gruppen #{link_to "Gemnasium", gemnasium} som tolkar många (men inte alla) ändringsloggar för öppen källkod. - + %h4#yanked %a.anchor{ href: "#yanked", aria_hidden: "true" } Hur är det med brådskande utgåvor ("yanked")? @@ -277,7 +277,7 @@ version: 1.0.0 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 viktigt att uppdatera din ändringslogg. - + %h4#contribute %a.anchor{ href: "#contribute", aria_hidden: "true" } Hur kan jag bidra? @@ -288,10 +288,10 @@ version: 1.0.0 %p Detta beror på att jag vill att vår gemenskap ska nå enighet. Jag tror på - att diskussionen är lika viktig som slutresultatet. + att diskussionen är lika viktig som slutresultatet. %p - Så tveka inte att #{link_to kasta dig in i diskussionen, gh}. + Så tveka inte att #{link_to "kasta dig in i diskussionen", gh}. .press %h3 Samtal diff --git a/source/tr-TR/1.0.0/index.html.haml b/source/tr-TR/1.0.0/index.html.haml new file mode 100644 index 0000000..e09ad75 --- /dev/null +++ b/source/tr-TR/1.0.0/index.html.haml @@ -0,0 +1,311 @@ +--- +description: Değişiklik kaydı tutun +title: Değişiklik kaydı tutun +language: tr-TR +version: 1.0.0 +--- + +- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.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/" +- iso = "http://www.iso.org/iso/home/standards/iso8601.htm" +- ghr = "https://help.github.com/articles/creating-releases/" + +.header + .title + %h1 Değişiklik kayıtları tutun + %h2 Arkadaşlarınızın, git mesajlarını değişiklik kayıtlarına yığmasını engelleyin. + + = link_to changelog do + Version + %strong= current_page.metadata[:page][:version] + + %pre.changelog= File.read("CHANGELOG.md") + +.answers + %h3#what + %a.anchor{ href: "#what", aria_hidden: "true" } + Nedir bu değişiklik kayıtları? + + %p + Değişiklik kayıtları bir proje için özel olarak hazırlanmış, + tarihsel sıralamayla sıralanmış, önemli değişikliklerin bir bütünüdür. + + %h3#why + %a.anchor{ href: "#why", aria_hidden: "true" } + Değişikliklerin kayıtlarını tutmanın anlamı ne? + + %p + Bir projenin kullanıcılarının ya da katılımcılarının, dağıtımlar + (ya da sürümler) arasındaki tam olarak hangi önemli değişikliklerin + olduğunu takip edebilmelerini sağlar. + + %h3#who + %a.anchor{ href: "#who", aria_hidden: "true" } + Kim değişiklik kayıtlarına ihtiyaç duyar ki? + + %p + İnsanlar. İster tüketici olsun, ister geliştirici, kullanılan yazılımın + son kullanıcıları, o yazılımın içinde ne olduğunu önemseyen kişilerdir. + Yazılım değiştiğinde, insanlar neden ve nasıl olduğunu bilmek isterler. + +.good-practices + %h3#how + %a.anchor{ href: "#how", aria_hidden: "true" } + Nası iyi değişiklik kayıtları tutarım? + + %h4#principles + %a.anchor{ href: "#principles", aria_hidden: "true" } + Rehber prensipler + + %ul + %li + Değişiklik kayıtları insanlar içindir, makineler için dğeil. + %li + Her sürüm için bir girdi içermelidir. + %li + Benzer değişiklikler gruplanmalıdır. + %li + SÜrümler ve bölümlere bağlantı verilebilir olmalıdır. + %li + En son sürüm ilk başta olur. + %li + Her sürümün dağıtım tarihi bulunmalıdır. + %li + Geliştirirken #{link_to "Anlamlı sürümlendirme", semver} kullanıp kullanmadığınızı bildirin. + + %a.anchor{ href: "#types", aria_hidden: "true" } + %h4#types Değişiklik tipleri + + %ul + %li + %code Eklendi + \: Yeni özellikler için. + %li + %code Değişti + \: Var olan becerilerde yapılan değişiklikler için. + %li + %code Rafa kalktı + \: Gelecekte yok olacak beceriler için. + %li + %code Kaldırıldı + \: Kaldırılan beceriler için. + %li + %code Düzeltildi + \: Ayıklanmış hatalar için. + %li + %code Güvenlik + \: Bir güvenlik açığı söz konusuysa. + +.effort + + %h3#effort + %a.anchor{ href: "#effort", aria_hidden: "true" } + Gerekli çabayı nasıl en aza indirebilirim? + + %p + Her zaman en üstte, değişiklikleri takip ettiğiniz bir Yayımlanmadı + bölümü olsun + + %p Bu, iki amaca hizmet eder: + + %ul + %li + İnsanlar gelecek sürümlerde karşılarına ne gibi değişiklikler çıkacağını görebilirler + %li + Dağıtım zamanı geldiğinde Yayımlanmadı bölümünü + yeni dağıtım sürümü bölümü olarak kullanabilirsiniz. + +.bad-practices + %h3#bad-practices + %a.anchor{ href: "#bad-practices", aria_hidden: "true" } + Değişiklik kütükleri kötü olabilirler mi? + + %p Evet. Buyrun size işe yaramayacak bir kaç örnek. + + %h4#log-diffs + %a.anchor{ href: "#log-diffs", aria_hidden: "true" } + Commit kayıtlarının farkları + + %p + Değişiklik kayıtları için commit kayıtlarının farklarını kullanmak + kötü bir fikirdir: genellikle çok gürültülü olurlar. Commit birleşmeleri, + kötü başlıklı commitler, belgeleme değişiklikleri vb. + + %p + Bir commit yapılmasının sebebi, kodun bir sonraki aşamaya evrilmesidir. + Bazı projeler commitleri temizler, bazıları temizlemez. + + %p + Değişiklik kayıtlarına eklenen bir girdi ise, öneme sahip bir değişikliğin + belgelenmesi amaçlıdır. Genelde bir çok commit işlemini kapsar ve son + kullanıcıyla iletişimi açık tutar. + + %h4#ignoring-deprecations + %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } + Rafa kalkanları göz ardı etmek + + %p + İnsanlar bir sürümden diğerine yükselttiklerinde, bir şeylerin bozulup + bozulmayacağı acı verici derecede açık olmalıdır. Rafa kalkan özelliklerin + listelendiği, sonra bu rafa kaldırılanlara yönelik kendi geliştirmelerini + yapabileceği ve sonrasında da özelliklerin tamamen kaldırıldığı sürüme + geçiş yapabilmeliler. + + %p + Eğer hiç bir şey yapmasanız bile, rafa kalkanlaı, kaldırılanları ve + önemli değişiklikleri değişiklik kayıtlarınızda listeleyin. + + + %h4#confusing-dates + %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } + Kafa karıştırıcı tarihler + + %p + A.B.D.'de insanlar ay kısmını önce kullanırken (2 Haziran 2012 için + 06-02-2012), dünyanın bir çok bölümünde daha robotik bir + kullanım 2 Haizran 2012 söz konusu. 2012-06-02 + biçimi en küçüğünden en büyüğüne tüm biçimlerle çalışmadan kullanılabiliyor + ve #{link_to "ISO standardı", iso}. Bu sebeple değişiklik kayıtlaro için + önerilen tarih biçimidir. + + %aside + Dahası da var. Bu karşıt desenleri toplamam için + = link_to "bir çağrı açın", "#issues" + ua da bir çekme isteği gönderin. + +.frequently-asked-questions + %h3#frequently-asked-questions + %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" } + Sıkça sorulan sorular + + %h4#standard + %a.anchor{ href: "#standard", aria_hidden: "true" } + Standart bir değişiklik kayıt biçimi var mı? + + %p + Pek sayılmaz. GNU değişiklik kayıtları sil rehberi mevcut ya da + iki paragraf GNU NEWS dosyası "guideline" var. İkisi de uygun + değiller ve yetersizler. + + %p + Bu proje daha iyi + = link_to "bir değişiklik kayıtları düzeni.", changelog + oluşturmaya çalışıyor. Bunun için de açık kaynaklı topluluklardaki, + en iyi kullanımları inceleyip, topluyoruz. + + %p + Sağlıklı eleştiriler, tartışmalar ve öneriler, projenin gelişmesi + için her zaman + = link_to "hoş karşılanır.", issues + + + %h4#filename + %a.anchor{ href: "#filename", aria_hidden: "true" } + Değişiklik kayıtları dosyasının ismi ne olmalı? + + %p + İsterseniz CHANGELOG.md olarak isimlendirin. Bazı projeler + HISTORY, NEWS ya da RELEASES + kullanıyor. + + %p + Dosya isminin çok da önemli olmadığını düşünebilirsiniz, fakat + nedne kullanıcılarınızın değişiklikleri taki edebilmesi için + onların işlerini zorlaştırasınız ki? + + %h4#github-releases + %a.anchor{ href: "#github-releases", aria_hidden: "true" } + GitHub dağıtımları ne olacak? + + %p + Harika bir girişim. #{link_to "Dağıtımlar", ghr} içine kendiniz + değişiklik kayıtları eklerseniz basit git etiketlerini + (örneğin v1.0.0) zengin dağıtım notlarına çevirebilir + ya da notlar eklenmiş git etiketlerinden oluşturulabilirsiniz. + + %p + GtHub dağıtımları sadece GitHub içeriğinde görüntülenebilecek, + taşınamaz değişiklik kayıtları oluşturur. Biraz emek harcayarak + "Keep a Changelog" biçimine uygun hale getirilebilir. + + %p + Ayrıca GitHub dağıtımlarının şu anki hali son kullanıcılar tarafından + çok kolay bulunabilir değil. Tipik büyük harfli dosyalar + (README, CONTRIBUTING, vb.) daha çok göze + çarpıyor. Bir başka konu da mevcut arayüz her dağıtım arasındaki + commit kayıtlarına bağlantı vermeye izin vermiyor.. + + %h4#automatic + %a.anchor{ href: "#automatic", aria_hidden: "true" } + Değişiklik kayıtları otomatik olarak toplanabilir mi? + + %p + Zor, çünkü insanlar bir çok farklı biçim ve dosya isimleri + kullanıyorlar. + + %p + #{link_to "Vandamme", vandamme}, #{link_to "Gemnasium", gemnasium} + ekibi tarafından oluşturulmuş bir Ruby Gem'i ve bir çok (ama hepsi + değil) açık kaynak projenin değişiklik kayıtlarını okuyabiliyor. + + + %h4#yanked + %a.anchor{ href: "#yanked", aria_hidden: "true" } + Peki ya Geri çekilen dağıtımlar? + + %p + Geri çekilen dağıtımlar, önemli hatalar ya da güvenlik sebepleri nedeniyle + yayından geri çekilen sürümlerdir. Genelde bu sürümler değişiklik kayıtlarında + görüntülenmezler. Görünmeliler. Tam da şu şekilde görünmeliler: + + %p ## 0.0.5 - 2014-12-13 [GERİ ÇEKİLDİ] + + %p + [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ılabilmesine + olanak sağlıyor. + + %h4#rewrite + %a.anchor{ href: "#rewrite", aria_hidden: "true" } + Değişiklik kayıtlarınızı tekrar yazmalı mısınız? + + %p + Tabii ki. Her zaman değişiklik kayıtlarını geliştirmek için iyi sebepler vardır. + Düzenli olarak açık kaynaklı projelerde bakım yapılmayan değişiklik kayıtları + için çekme istekleri yapıyorum. + + %p + Ayrıca bir sürümdeki notların arasında önemli bir değişiklikten bahsetmeyi + unutmuş olduğunuzu fark edebilirsiniz. Değişiklik kayıtlarınızı bu bilgi ışığında + güncellemeniz gerektiği gün gibi ortada. + + %h4#contribute + %a.anchor{ href: "#contribute", aria_hidden: "true" } + Nasıl katkıda bulunabilirim? + + %p + Bu belge doğrunun kendisi değil; benim ince eleyip + sık dokuduğum görüşlerimdir. Beraberinde toparlamış olduğum bilgiler + ve örnekler bulunur. + + %p + Bunu istememin sebebi topluluğun ortak bir paydada buluşmasını istememdir. + İnanıyorum ki tartışmanın kendisi de sonucu kadar önemli. + + %p + Yani, lütfen #{link_to "siz de katılın", gh}. + +.press + %h3 Sohbetler + %p + Geliştiricilerin ve katkıda bulunanların neden değişiklik kayıtlarını + dikkate almaları gerekliliğini ve bu projenin arkasındaki motivasyonu + anlattığım #{link_to "Değişiklik Kayıtları podcast", thechangelog}'ini + inceleyebilirsiniz.