diff --git a/CHANGELOG.md b/CHANGELOG.md index cac12d1..75af7e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - French translation from @zapashcanon. - Brazilian Portugese translation from @aisamu. - Polish translation from @amielucha. +- Russian translation from @aishek. ### Changed - Start using "changelog" over "change log" since it's the common usage. 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..47b612f --- /dev/null +++ b/source/ru/1.0.0/index.html.haml @@ -0,0 +1,303 @@ +--- +description: Keep a Changelog +title: Keep a Changelog +language: ru +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 Ведите CHANGELOG + %h2 Не позволяйте друзьям сливать логи гита в CHANGELOG™ + + = 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" } + Что такое лог изменений? + + %p + Лог изменений – это файл, который содержит поддерживаемый, хронологически + упорядоченный список изменений для каждой версии проекта. + + %h3#why + %a.anchor{ href: "#why", aria_hidden: "true" } + Зачем вести лог изменений? + + %p + Чтобы пользователям и контрибьюторам было проще точно понять, + какие изменения были сделаны в каждом релизе (или версии) проекта + + %h3#who + %a.anchor{ href: "#who", aria_hidden: "true" } + Кому нужен лог изменений? + + %p + Людям. Будь то клиенты или разработчики, конечные пользователи программного обеспечения + это люди, и им важно, с чем они работают. Когда программное обеспечение меняется, + люди хотят знать почему и что изменилось. + +.good-practices + %h3#how + %a.anchor{ href: "#how", aria_hidden: "true" } + Как мне сделать хороший лог изменений? + + %h4#principles + %a.anchor{ href: "#principles", aria_hidden: "true" } + Главные принципы + + %ul + %li + Лог изменений ведётся для людей, не для машин. + %li + Для каждой версии должен быть отдельный раздел. + %li + Одинаковые типы изменений должны быть сгруппированы. + %li + Должна быть возможность поставить ссылку на любую версию или раздел. + %li + Последняя версия должна идти в начале файла. + %li + У каждой версии указана дата выпуска. + %li + Уточните, следуете ли вы принципам #{link_to "Семантического версионирования", semver} + + %a.anchor{ href: "#types", aria_hidden: "true" } + %h4#types Типы изменений + + %ul + %li + %code Добавлено + для новых функций. + %li + %code Изменено + для изменений в существующей функциональности. + %li + %code Устарело + для функций, которы скоро будут удалены. + %li + %code Удалено + для удалённых функций. + %li + %code Исправлено + для любых исправлений. + %li + %code Безопасность + в случае уязвимостей. + +.effort + + %h3#effort + %a.anchor{ href: "#effort", aria_hidden: "true" } + Как мне тратить меньше усилий на ведение лога изменений? + + %p + Ведите раздел Новое с изменениями для новой версии в начале файла. + + %p Это нужно для двух вещей: + + %ul + %li + Люди смогут видеть, каких изменений им ожидать в ближайших релизах + %li + В момент релиза вы можете переместить изменения раздела Новое + в раздел нового релиза. + +.bad-practices + %h3#bad-practices + %a.anchor{ href: "#bad-practices", aria_hidden: "true" } + Бывают плохие логи изменений? + + %p Да. Вот несколько способов чтобы сделать их не такими полезными. + + %h4#log-diffs + %a.anchor{ href: "#log-diffs", aria_hidden: "true" } + Диффы лога коммитов + + %p + Использование диффов лога коммитов это плохая идея: они очень шумные. + Шумят мердж-коммиты, коммиты с непонятными названиями, изменения в документации + и тому подобное. + + %p + Назначение коммита в том, чтобы задокументировать шаг в эволюции исходного + кода. В некоторых проектах следят за историей коммитов, в некоторых нет. + + %p + Назначение же раздела в логе изменений — задокументировать ключевые различия, + часто между несколькими коммитами, чтобы ясно донести их назначение + до конечных пользователей. + + + %h4#ignoring-deprecations + %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } + Игнорирование устаревающих функций + + %p + Когда люди обновляются с одной версии на другую, должно быть до боли + очевидно, что сломается. Должна быть возможность обновиться до версии, которая + перечисляет устаревающие функции, удалить устаревшие данные, затем обновиться до версии, + в которой устаревающие функции становятся удалёнными. + + %p + Если вы не ведёте лог изменений, то хотя бы указывайте в нём устаревающие + и удалённые функции, а также все критичные изменения. + + %h4#confusing-dates + %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } + Непонятные даты + + %p + В США сначала пишут месяц (06-02-2012 для 2 июня 2012), + в то время как большинство людей в остальном мире пишут роботоподобное + 2 июня 2012, произнося эту дата по-разному. Запись + 2012-06-02 логично идёт от большего к меньшему, не пересекается + с большинством других форматов дат, и является #{link_to "стандартом ISO", iso}. + Поэтому именно такой формат рекомендуется для логов изменений. + + %aside + Есть и другие. Помогите мне собрать эти антипаттерны, + = link_to "создав тикет", "#issues" или пулл-реквест. + +.frequently-asked-questions + %h3#frequently-asked-questions + %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" } + Часто задаваемые вопросы + + %h4#standard + %a.anchor{ href: "#standard", aria_hidden: "true" } + Существует ли стандарт формата логов изменений? + + %p + На самом деле нет. Есть стайлгайд логов изменений GNU, + есть длиной-в-два-параграфа файл "guideline" GNU NEWS. + Оба или неадекватны или недостаточно полны. + + %p + Цель этого проекта — стать + = link_to "улучшенной версией соглашения о формате логов изменений.", changelog + Это приходит из-за сбора и следования хорошим практикам сообщества. + + %p + Здоровая критика, дискуссии и предложения по улучшению + = link_to "приветствуются.", issues + + + %h4#filename + %a.anchor{ href: "#filename", aria_hidden: "true" } + Как назвать файл лога изменений? + + %p + Назовите его CHANGELOG.md. Некоторые проекты также используют + HISTORY, NEWS или RELEASES. + + %p + Хоть и легко подумать, что имя файла лога изменений не так уж и важно, + но зачем усложнять вашим конечным пользователям поиск места, + где описаны все ключевые изменения? + + %h4#github-releases + %a.anchor{ href: "#github-releases", aria_hidden: "true" } + Что насчёт функции "Релизы" на Гитхабе? + + %p + Это отличная инициатива. #{link_to "Релизы", ghr} могут использоваться + для превращения простых тегов в Git (наприме тег v1.0.0) + в подробные заметки к релизам с помощью их редактирования вручную, + или с помощью комментариев к таким тегам. + + %p + Релизы на Гитхабе создают непереносимый лог изменений, который может + быть показан пользователям только на самом Гитхабе. Возможно вести + их в формате, близком к формату проекта Keep a Changelog, но это требует + больших усилий. + + %p + Текущая версия Релизов на Гитхабе также возможно не так хорошо видна + для конечных пользователей, в отличии от обычных файлов с именами в верхнем + регистре (README, CONTRIBUTING, и так далее). + Другая небольшая проблема заключается в том, что интерфейс не предлагает + ссылок на логи коммитов между релизами. + + %h4#automatic + %a.anchor{ href: "#automatic", aria_hidden: "true" } + Могут ли логи изменений быть автоматически распарсены? + + %p + Это сложно, потому что люди следуют сильно различающимся форматам + и используют разные имена файлов. + + %p + #{link_to "Vandamme", vandamme} это гем для Руби, созданный командой + #{link_to "Gemnasium", gemnasium}, который парсит многие (но не все) + логи изменений проектов с открытым исходным кодом. + + + %h4#yanked + %a.anchor{ href: "#yanked", aria_hidden: "true" } + Что насчёт yanked-релизов? + + %p + Yanked-релизы – это версии, которые изымаются из обращения из-за серьёзного + бага или проблемы безопасности в них. Часто такие версии даже не упоминаются + в логах изменений. А должны. И вот как вам следует их упоминать: + + %p ## 0.0.5 - 2014-12-13 [YANKED] + + %p + Тег [YANKED] так бросается в глаза специально. Очень важно, + чтобы люди его заметели. Так как он обрамлён квадратными скобками, + его также проще распарсить программно. + + + %h4#rewrite + %a.anchor{ href: "#rewrite", aria_hidden: "true" } + Имеет ли смысл переписывать лог изменений? + + %p + Конечно. Всегда есть веские причины для улучшения лога изменений. + Я регулярно открываю пулл-реквесты по добавлению недостающих релизов + в проекты с открытым исходным кодом с брошенными логами изменений. + + %p + Также возможно вы можете обнаружить, что вы забыли указать критичное + изменение в замечаниям к версии. В этом случае очевидно вам важно + обновить ваш лог изменений. + + %h4#contribute + %a.anchor{ href: "#contribute", aria_hidden: "true" } + Как я могу помочь вашему проекту? + + %p + Этот документ не истина в последней инстанции; это моё + тщательно обдуманное мнение, вместе с информацией и примерами, которые я собрал. + + %p + Дело в том, что я хочу, чтобы наше сообщество достигло согласия в этом вопросе. + Я верю, что дискуссия также важна, как и конечный результат. + + %p + Так что, пожалуйста, #{link_to "участвуйте", gh}. + +.press + %h3 Обсуждения + %p + Я приходил в #{link_to "подкаст The Changelog", thechangelog}, + чтобы поговорить о том, почему мейнтейнеры и контрьбьюторы долны вести логи изменений, + а также о моей мотивации к созданию этого проекта.