diff --git a/.gitignore b/.gitignore index 865ecdb..ef48534 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ /.sass-cache /build /_site +/.vs diff --git a/CHANGELOG.md b/CHANGELOG.md index 9324ba8..cac12d1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,8 @@ # 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] @@ -17,7 +17,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/). - "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. diff --git a/Gemfile.lock b/Gemfile.lock index 82ee853..a8534db 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,16 +1,16 @@ GEM remote: https://rubygems.org/ specs: - activesupport (4.2.7) + activesupport (5.0.4) + concurrent-ruby (~> 1.0, >= 1.0.2) i18n (~> 0.7) - json (~> 1.7, >= 1.7.7) minitest (~> 5.1) - thread_safe (~> 0.3, >= 0.3.4) tzinfo (~> 1.1) - addressable (2.4.0) - autoprefixer-rails (6.7.7.2) + addressable (2.5.1) + public_suffix (~> 2.0, >= 2.0.2) + autoprefixer-rails (7.1.1.2) execjs - backports (3.6.8) + backports (3.8.0) coderay (1.1.1) coffee-script (2.4.1) coffee-script-source @@ -18,9 +18,9 @@ GEM coffee-script-source (1.12.2) compass-import-once (1.0.5) sass (>= 3.2, < 3.5) - concurrent-ruby (1.0.2) + concurrent-ruby (1.0.5) contracts (0.13.0) - dotenv (2.1.1) + dotenv (2.2.1) em-websocket (0.5.1) eventmachine (>= 0.12.9) http_parser.rb (~> 0.6.0) @@ -28,43 +28,42 @@ GEM eventmachine (1.2.0.1) execjs (2.7.0) fast_blank (1.0.0) - fastimage (2.0.0) - addressable (~> 2) - ffi (1.9.14) - haml (4.0.7) + fastimage (2.1.0) + ffi (1.9.18) + haml (5.0.1) + temple (>= 0.8.0) tilt hamster (3.0.0) concurrent-ruby (~> 1.0) - hashie (3.4.4) + hashie (3.5.5) htmlcompressor (0.2.0) http_parser.rb (0.6.0) i18n (0.7.0) - json (1.8.3) - kramdown (1.11.1) + kramdown (1.13.2) listen (3.0.8) rb-fsevent (~> 0.9, >= 0.9.4) rb-inotify (~> 0.9, >= 0.9.7) - memoist (0.14.0) + memoist (0.16.0) method_source (0.8.2) - middleman (4.1.10) + middleman (4.1.14) coffee-script (~> 2.2) compass-import-once (= 1.0.5) haml (>= 4.0.5) kramdown (~> 1.2) - middleman-cli (= 4.1.10) - middleman-core (= 4.1.10) + middleman-cli (= 4.1.14) + middleman-core (= 4.1.14) sass (>= 3.4.0, < 4.0) - middleman-autoprefixer (2.7.0) - autoprefixer-rails (>= 6.3.1, < 7.0.0) + middleman-autoprefixer (2.8.0) + autoprefixer-rails (>= 7.0.1, < 8.0.0) middleman-core (>= 3.3.3) middleman-blog (4.0.1) addressable (~> 2.3) middleman-core (>= 4.0.0) tzinfo (>= 0.3.0) - middleman-cli (4.1.10) + middleman-cli (4.1.14) thor (>= 0.17.0, < 2.0) - middleman-core (4.1.10) - activesupport (~> 4.2) + middleman-core (4.1.14) + activesupport (>= 4.2, < 5.1) addressable (~> 2.3) backports (~> 3.6) bundler (~> 1.1) @@ -81,10 +80,10 @@ GEM memoist (~> 0.14) padrino-helpers (~> 0.13.0) parallel - rack (>= 1.4.5, < 2.0) + rack (>= 1.4.5, < 3) sass (>= 3.4) servolux - tilt (~> 1.4.1) + tilt (~> 2.0) uglifier (~> 3.0) middleman-gh-pages (0.0.3) rake (> 0.9.3) @@ -98,34 +97,36 @@ GEM middleman-syntax (3.0.0) middleman-core (>= 3.2) rouge (~> 2.0) - minitest (5.9.0) - padrino-helpers (0.13.2) + minitest (5.10.2) + padrino-helpers (0.13.3.4) i18n (~> 0.6, >= 0.6.7) - padrino-support (= 0.13.2) + padrino-support (= 0.13.3.4) tilt (>= 1.4.1, < 3) - padrino-support (0.13.2) + padrino-support (0.13.3.4) activesupport (>= 3.1) - parallel (1.9.0) + parallel (1.11.2) pry (0.10.3) coderay (~> 1.1.0) method_source (~> 0.8.1) slop (~> 3.4) - rack (1.6.4) + public_suffix (2.0.5) + rack (2.0.3) rack-livereload (0.3.16) rack rake (10.4.2) - rb-fsevent (0.9.7) - rb-inotify (0.9.7) - ffi (>= 0.5.0) + rb-fsevent (0.9.8) + rb-inotify (0.9.10) + ffi (>= 0.5.0, < 2) redcarpet (3.4.0) rouge (2.0.5) - sass (3.4.22) - servolux (0.12.0) + sass (3.4.24) + servolux (0.13.0) slop (3.6.0) - thor (0.19.1) - thread_safe (0.3.5) - tilt (1.4.1) - tzinfo (1.2.2) + temple (0.8.0) + thor (0.19.4) + thread_safe (0.3.6) + tilt (2.0.7) + tzinfo (1.2.3) thread_safe (~> 0.1) uglifier (3.2.0) execjs (>= 0.3.0, < 3) diff --git a/config.rb b/config.rb index 6f5f887..d217b5c 100644 --- a/config.rb +++ b/config.rb @@ -187,7 +187,7 @@ configure :build do .txt .woff ]} - set :haml, {ugly: true, attr_wrapper: '"'} + set :haml, { attr_wrapper: '"' } activate :minify_css activate :minify_html do |html| html.remove_quotes = false 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/assets/javascripts/all.js b/source/assets/javascripts/all.js index bec14c6..e84aec9 100644 --- a/source/assets/javascripts/all.js +++ b/source/assets/javascripts/all.js @@ -21,7 +21,7 @@ document.addEventListener("DOMContentLoaded", function(){ paragraphs = []; paragraphs.push(lastParagraph); - while (lastParagraph.nextElementSibling.tagName == "P") { + while (lastParagraph.nextElementSibling && lastParagraph.nextElementSibling.tagName == "P") { lastParagraph = lastParagraph.nextElementSibling; paragraphs.push(lastParagraph) } 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/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/ru/1.0.0/index.html.haml b/source/ru/1.0.0/index.html.haml new file mode 100644 index 0000000..1c6c2c6 --- /dev/null +++ b/source/ru/1.0.0/index.html.haml @@ -0,0 +1,197 @@ +--- +description: Ведите Changelog +title: Ведите Changelog +language: en +version: 0.3.0 +--- + +:markdown + # Ведите CHANGELOG + + ## Не позволяйте друзьям сливать логи гита в CHANGELOG™ + + Version **#{current_page.metadata[:page][:version]}** + + ### Что такое лог изменений? + Лог изменений – это файл, который содержит поддерживаемый, хронологически упорядоченный + список изменений для каждой версии проекта. + +%pre.changelog= File.read("CHANGELOG.md") + +:markdown + ### Для чего нужен лог изменений? + Чтобы пользователи и контрибьюторы чётко понимали что поменялось в каждом релизе (или + версии) проекта. + + ### Почему я вообще должен задумываться о таких вещах? + Потому, что инструменты программирования делаются для людей. Если вам пофигу, + зачем вы вообще занимаетесь программным обеспечением с открытым исходным + кодом? У вас обязательно в голове должен быть центр «не пофигу» :) + + Я [беседовал с Адамом Стаковиаком и с Джеродом Санто в подкасте The + Changelog][thechangelog] (в тему название, правда?) о том почему авторам + программного обеспечения с открытым исходным кодом и их коллегам должно быть + не пофигу, и о моих мотивах в создании этого проекта. Послушайте, если у вас + есть время (1:06). + + ### Что должно быть в хорошем логе изменений? + Я рад, что вы спросили. + + Хороший лог изменений построен на таких приниципах: + + - Он сделан для людей, а не машин, так что понятность имеет решающее + значение. + - Легко сослаться на любой раздел (поэтому Markdown лучше обычного текста). + - Один подраздел на каждую версию. + - Релизы перечислены в обратном хронологическом порядке (самые новые – + сверху). + - Пишите все даты в формате `YYYY-MM-DD`. (Например: `2012-06-02` для даты `2 + июня 2012`.) Он международный, [рациональный](http://xkcd.com/1179/), и + независим от языка. + - Ясно указывает, использует ли проект [Семантическое + Версионирование][semver]. + - Каждая версия должна: + - Показывать дату релиза в формате, упомянутом выше. + - Группировать изменения согласно их влиянию на проект следующим образом: + - `Added` для новых функций. + - `Changed` для изменений в существующей функциональности. + - `Deprecated` для функциональности, которая будет удалена в следующих + версиях. + - `Removed` для функциональности, которая удалена в этой версии. + - `Fixed` для любых исправлений. + - `Security` для обновлений безопасности. + + ### Как минимизировать время, необходимое для ведения лога изменений? + Всегда ведите секцию `Unreleased` в начале файла, чтобы держать в ней не + выпущенные изменения. + + Это нужно для двух вещей: + + - Люди смогут видеть, какие изменения ожидаются в ближайших релизах + - В момент релиза вам нужно всего лишь заменить секцию `Unreleased` на номер + версии и добавить новую секцию `Unreleased` в начале файла. + + ### Что заставляет плакать единорогов? + Хорошо… давайте разберёмся. + + - **Выгрузка изменений лога коммитов.** Просто не делайте так, это никому не + принесёт пользы. + - **Отсутствие отметок планируемой к удалению функциональности.** Когда люди + обновляются от одной версии к другой, им должно быть очевидно до боли, что + сломается. + - **Даты в местном формате.** В Соединённых Штатах, люди сначала пишут месяц + («06-02-2012» для даты 2 июня 2012, что не имеет *никакого* смысла), хотя + много людей в остальном мире пишет роботоподобное «2 июня 2012», всё ещё + произнося это по-другому. «2012-06-02» логично работает от самого большого + к самому маленькому, не пересекается с другими форматами дат, и является + [стандартом ISO](http://www.iso.org/iso/home/standards/iso8601.htm). Таким + образом, этот формат является рекомендуемым для логов изменений. + + Существуют и другие. Помогите мне собрать слёзы единорогов, + [открыв тикет][issues] или пулл-реквест. + + ### Существует стандарт формата лога изменений? + К сожалению, нет. Спокойней. Я знаю, что вы яростно бросились на поиски + ссылки на GNU-руководства по стилю лога изменений, или на поиски файла + «guideline» с парой параграфов в GNU NEWS. GNU-руководство по стилю неплохо + для начала, но оно наивно. В наивности нет ничего плохого, но когда людям + нужно руководство, она редко бывает полезна. Особенно, когда приходиться + сталкиваться со множеством краевых случаев. + + Этот проект [содержит информацию, которая, я надеюсь, станет соглашением + получше о ведении файлов CHANGELOG][CHANGELOG] для всех проектов с открытым + исходным кодом. Может ли сообщество учиться на своих ошибках, а не просто + действовать согласно десяти записям, которые были написаны много лет назал, + и, якобы, без одной ошибки? Хорошо. Поэтому, пожалуйста, посмотрите вокруг, и + помните, что [обсуждения и предложения по улучшению приветствуются][issues]! + + ### Как можно назвать файл лога изменений? + Ну, если вы не не можете ответить на этот вопрос, глядя на пример выше, + `CHANGELOG.md` пока наилучший вариант. + + Некоторые проекты используют `HISTORY.txt`, `HISTORY.md`, `History.md`, + `NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, + `releases.md`, и так далее. + + Это непорядок. Все эти имена только усложняют поиск нужного файла. + + ### Почему люди не могут использовать просто дифф команды `git log`? + Потому, что диффы логов по своей природе содержат слишком много «шума». С их + помощью невозможно сделать подходящий лог изменений даже в гипотетическом + проекте, который делается идеальными программистами, которые никогда не + делают опечаток, никогда не забывают коммитить новые файлы, никогда не + пропускают ни одну часть рефакторинга. Назначение коммита в том, чтобы + задокументировать один атомарный шаг в процессе развития кода от одного + состояния к другому. Назначение лога изменений – документировать значимые + различия между этими состояниями. + + Как отличаются хорошие комментарии к коду и сам код, также отличаются друг от + друга и лог изменений с логом коммитов: первые отвечают на вопрос + *почему*, а вторые на вопрос как. + + ### Могут ли логи изменений быть автоматически распарсены? + Это сложно из-за того, что люди следуют сильно отличающимся форматам и + соглашениям о именах файлов. + + Гем для Руби [Vandamme][vandamme], который создали в команде + [Gemnasium][gemnasium], парсит многие (но не все) логи изменений проектов с + открытым исходным кодом. + + ### Почему вы пишите то «CHANGELOG», то «лог изменений»? + «CHANGELOG» – это имя файла. Оно несколько крикливо, но это историческое + соглашение, которому следуют многие проекты с открытым исходным кодом. В + качестве примеров подобных файлов можно привести [`README`][README], + [`LICENSE`][LICENSE], и [`CONTRIBUTING`][CONTRIBUTING]. + + Верхний регистр в имени файла (который в старых операционных системах + заставляет эти файлы находиться наверху списков) используется для привлечения + внимания. Так как в этих файлах содержится важная метаинформация о проекте, + они могут быть полезны любому использующему или дорабатывющему проект, также + как [бейджи проектов с открытым исходным кодом][shields]. + + Когда я упоминаю «лог изменений», я говорою о назначении этого файла: об + учёте изменений. + + ### Как насчёт yanked-релизов? + Yanked-релизы – это версии, которые изымаются из обращения из-за серьёзного + бага или проблемы безопасности в них. Часто такие версии даже не упоминаются + в логах изменений. А должны. И вот как вам следует их упоминать: + + `## 0.0.5 - 2014-12-13 [YANKED]` + + Тег `[YANKED]` такой «громкий» не просто так. Очень важно, чтобы люди его + заметили. А из-за того, что он окружён скобками, его легче определить + программно. + + ### Стоит ли переписывать лог изменений? + Конечно. Всегда есть причины для улучшения лога изменений. Я регулярно + открываю пулл-реквесты в проекты с открытым исходным кодом с + неподдерживаемыми логами изменений для добавления недостающих релизов. + + Также вы можете обнаружить что вы забыли адресовать критичное изменение в + описании версии. В этом случае очевидно, что нужно обновить лог + изменений. + + ### Как я могу помочь вашему проекту? + Этот документ **не истина в последней инстанции**; это моё тщательно + сформулированное мнение вместе с информацией и примерами, которые я собрал. + Хотя я предоставил настоящий [CHANGELOG][] из [GitHub-репозитария][gh], я + специально избегал цели создать *стандарт* или чёткий список правил (как это + делает, например, [SemVer.org][semver]). + + Я сделал это потому, что хочу, чтобы наше сообщество достигло консенсуса. Я + верю, что дискуссия также важна, как и её результат. + + Так что, пожалуйста, [**участвуйте**][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/1.0.0/index.html.haml b/source/sv/1.0.0/index.html.haml new file mode 100644 index 0000000..aeb27c7 --- /dev/null +++ b/source/sv/1.0.0/index.html.haml @@ -0,0 +1,301 @@ +--- +description: Håll en ändringslogg +title: Håll en ändringslogg +language: sv +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 Håll en ändringslogg + %h2 Låt inte dina vänner slänga in git-loggar i ändringsloggar. + + = 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" } + Vad är en ändringslogg? + + %p + En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad + lista över viktiga ändringar för varje version av ett projekt. + + %h3#why + %a.anchor{ href: "#why", aria_hidden: "true" } + Vad är meningen med en ändringslogg? + + %p + För att göra det enklare för användare och medarbetare att se exakt vilka + viktiga ändringar som har gjorts mellan varje utgåva (eller version) av projektet. + + %h3#who + %a.anchor{ href: "#who", aria_hidden: "true" } + Vem behöver en ändringslogg? + + %p + Alla behöver det. Oavsett om det är användare eller utvecklare, är + alla slutanvändare av mjukvaran människor som bryr sig vad som finns + i mjukvaran. När mjukvaran förändras vill folk veta varför och hur. + +.good-practices + %h3#how + %a.anchor{ href: "#how", aria_hidden: "true" } + Hur gör jag en bra ändringslogg? + + %h4#principles + %a.anchor{ href: "#principles", aria_hidden: "true" } + Riktlinjer + + %ul + %li + Ändringsloggar är för människor, inte maskiner. + %li + Det bör finnas en post för varje enskild version. + %li + Samma typ av ändringar bör grupperas. + %li + Det bör vara möjligt att länka till versioner och sektioner. + %li + Senaste versionen kommer först. + %li + Datum då respektive version släpptes ska visas. + %li + Notering att du följer #{link_to "Semantisk versionshantering", semver}. + + %a.anchor{ href: "#types", aria_hidden: "true" } + %h4#types Typer av ändringar + + %ul + %li + %code Added + för nya funktioner. + %li + %code Changed + för ändringar på existerande funktionalitet. + %li + %code Deprecated + för funktionalitet som snart tas bort. + %li + %code Removed + för nu borttagen funktionalitet. + %li + %code Fixed + för alla buggfixar + %li + %code Security + i fall av sårbarheter. + +.effort + + %h3#effort + %a.anchor{ href: "#effort", aria_hidden: "true" } + Hur kan jag minimera den insats som krävs för att underhålla en ändringslogg? + + %p + Ha en sektion kallad Unreleased högst upp för att hålla reda på + kommande ändringar. + + %p Detta tjänar två syften: + + %ul + %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 + Unreleased till en ny versionspost. + +.bad-practices + %h3#bad-practices + %a.anchor{ href: "#bad-practices", aria_hidden: "true" } + Kan ändringsloggar vara dåliga? + + %p Ja, här är några exempel på då de är mindre användbara. + + %h4#log-diffs + %a.anchor{ href: "#log-diffs", aria_hidden: "true" } + 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 + otydliga titlar, dokumentationsförändringar etc. + + %p + Syftet med en incheckning är att dokumentera ett steg i utvecklingen av + källkoden. Vissa projekt städar upp bland incheckningarna, andra inte. + + %p + Syftet med en post i en ändringslogg är att dokumentera den noterbara + skillnaden, oftast över flera incheckningar, för att kommunicera dessa + tydligt till slutanvändaren. + + %h4#ignoring-deprecations + %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } + Ignorera föråldrad funktionalitet (deprecations) + + %p + 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 + 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 + funktionalitet samt förstörande förändringar i din ändringslogg. + + %h4#confusing-dates + %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } + 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 + datumformat för ändringsloggar. + + %aside + Det finns mer. Hjälp mig att samla dessa antimönster genom att + = link_to "skapa ett issue", "#issues" + eller en pull requests + +.frequently-asked-questions + %h3#frequently-asked-questions + %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" } + Vanliga frågor + + %h4#standard + %a.anchor{ href: "#standard", aria_hidden: "true" } + 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. + + %p + Detta projekt har som mål att bli + = link_to "en bättre konvention för ändringsloggar.", changelog + Det utgår från uppenbart goda praxis från öppen källkods-världen och sammanför dem. + + %p + Konstruktiv kritik, diskussion och förslag till förbättring + = link_to "är välkommen.", issues + + %h4#filename + %a.anchor{ href: "#filename", aria_hidden: "true" } + Vad bör filen med ändringsloggen heta? + + %p + Döp den till CHANGELOG.md. En del projekt använder + HISTORY, NEWS eller RELEASES. + + %p + Även om det är lätt att tänka att det inte spelar så stor roll vad filen + med ändringsloggar kallas, varför göra det svårare för dina slutanvändare + att enkelt hitta de viktigaste ändringarna? + + %h4#github-releases + %a.anchor{ href: "#github-releases", aria_hidden: "true" } + Hur är det med GitHub Releases? + + %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 + 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.). + Ett annat bekymmer är att användargränssnittet för närvarande inte + erbjuder länkar till incheckningsloggar mellan olika versioner. + + %h4#automatic + %a.anchor{ href: "#automatic", aria_hidden: "true" } + Kan ändringsloggar bli automatiskt tolkade? + + %p + 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 "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")? + + %p + Brådskande utgåvor är versioner som måste släppas på grund av alvarliga + buggar eller säkerhetsproblem. Oftast brukar dessa versioner inte ens + finnas med i ändringsloggarna. De borde det. Så här borde du visa dem: + + %p ## 0.0.5 - 2014-12-13 [YANKED] + + %p + Taggen [YANKED] står ut av en anledning, det är viktigt + att folk se det. Då den är omsluten med hakparenteser är det också lättare + för ett program att tolka det. + + %h4#rewrite + %a.anchor{ href: "#rewrite", aria_hidden: "true" } + Borde du någonsin förändra en ändringslogg? + + %p + Självklart. Det finns alltid en bra anledning att förbättra en ändringslogg. + Jag öppnar regelbundet pull requests för att lägga till saknade utgåvor + för öppna källkodsprojekt som inte tar hand om sin ändringslogg. + + %p + 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? + + %p + Detta dokument är inte sanningen, det är en noga övervägd + åsikt tillsammans med information och exempel jag har samlat på mig. + + %p + Detta beror på att jag vill att vår gemenskap ska nå enighet. Jag tror på + att diskussionen är lika viktig som slutresultatet. + + %p + Så tveka inte att #{link_to "kasta dig in i diskussionen", gh}. + +.press + %h3 Samtal + %p + Jag var med i #{link_to "The Changelog podcast", thechangelog} + för att prata om varför förvaltare och bidragsgivare bör bry sig om + ändringsloggar, och motiveringen bakom detta projekt. diff --git a/source/tr-TR/1.0.0/index.html.haml b/source/tr-TR/1.0.0/index.html.haml index 0f9ac2e..dc0ce95 100644 --- a/source/tr-TR/1.0.0/index.html.haml +++ b/source/tr-TR/1.0.0/index.html.haml @@ -1,7 +1,7 @@ --- description: Değişiklik kaydı tutun title: Değişiklik kaydı tutun -language: tr +language: tr-TR version: 1.0.0 ---