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 index 1c6c2c6..47b612f 100644 --- a/source/ru/1.0.0/index.html.haml +++ b/source/ru/1.0.0/index.html.haml @@ -1,197 +1,303 @@ --- -description: Ведите Changelog -title: Ведите Changelog -language: en -version: 0.3.0 +description: Keep a Changelog +title: Keep a Changelog +language: ru +version: 1.0.0 --- -:markdown - # Ведите CHANGELOG +- 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/" - ## Не позволяйте друзьям сливать логи гита в CHANGELOG™ +.header + .title + %h1 Ведите CHANGELOG + %h2 Не позволяйте друзьям сливать логи гита в CHANGELOG™ - Version **#{current_page.metadata[:page][:version]}** + = link_to changelog do + Version + %strong= current_page.metadata[:page][:version] - ### Что такое лог изменений? - Лог изменений – это файл, который содержит поддерживаемый, хронологически упорядоченный - список изменений для каждой версии проекта. + %pre.changelog= File.read("CHANGELOG.md") -%pre.changelog= File.read("CHANGELOG.md") +.answers + %h3#what + %a.anchor{ href: "#what", aria_hidden: "true" } + Что такое лог изменений? -:markdown - ### Для чего нужен лог изменений? - Чтобы пользователи и контрибьюторы чётко понимали что поменялось в каждом релизе (или - версии) проекта. + %p + Лог изменений – это файл, который содержит поддерживаемый, хронологически + упорядоченный список изменений для каждой версии проекта. - ### Почему я вообще должен задумываться о таких вещах? - Потому, что инструменты программирования делаются для людей. Если вам пофигу, - зачем вы вообще занимаетесь программным обеспечением с открытым исходным - кодом? У вас обязательно в голове должен быть центр «не пофигу» :) + %h3#why + %a.anchor{ href: "#why", aria_hidden: "true" } + Зачем вести лог изменений? - Я [беседовал с Адамом Стаковиаком и с Джеродом Санто в подкасте The - Changelog][thechangelog] (в тему название, правда?) о том почему авторам - программного обеспечения с открытым исходным кодом и их коллегам должно быть - не пофигу, и о моих мотивах в создании этого проекта. Послушайте, если у вас - есть время (1:06). + %p + Чтобы пользователям и контрибьюторам было проще точно понять, + какие изменения были сделаны в каждом релизе (или версии) проекта - ### Что должно быть в хорошем логе изменений? - Я рад, что вы спросили. + %h3#who + %a.anchor{ href: "#who", aria_hidden: "true" } + Кому нужен лог изменений? - Хороший лог изменений построен на таких приниципах: + %p + Людям. Будь то клиенты или разработчики, конечные пользователи программного обеспечения + это люди, и им важно, с чем они работают. Когда программное обеспечение меняется, + люди хотят знать почему и что изменилось. - - Он сделан для людей, а не машин, так что понятность имеет решающее - значение. - - Легко сослаться на любой раздел (поэтому Markdown лучше обычного текста). - - Один подраздел на каждую версию. - - Релизы перечислены в обратном хронологическом порядке (самые новые – - сверху). - - Пишите все даты в формате `YYYY-MM-DD`. (Например: `2012-06-02` для даты `2 - июня 2012`.) Он международный, [рациональный](http://xkcd.com/1179/), и - независим от языка. - - Ясно указывает, использует ли проект [Семантическое - Версионирование][semver]. - - Каждая версия должна: - - Показывать дату релиза в формате, упомянутом выше. - - Группировать изменения согласно их влиянию на проект следующим образом: - - `Added` для новых функций. - - `Changed` для изменений в существующей функциональности. - - `Deprecated` для функциональности, которая будет удалена в следующих - версиях. - - `Removed` для функциональности, которая удалена в этой версии. - - `Fixed` для любых исправлений. - - `Security` для обновлений безопасности. +.good-practices + %h3#how + %a.anchor{ href: "#how", aria_hidden: "true" } + Как мне сделать хороший лог изменений? - ### Как минимизировать время, необходимое для ведения лога изменений? - Всегда ведите секцию `Unreleased` в начале файла, чтобы держать в ней не - выпущенные изменения. + %h4#principles + %a.anchor{ href: "#principles", aria_hidden: "true" } + Главные принципы - Это нужно для двух вещей: + %ul + %li + Лог изменений ведётся для людей, не для машин. + %li + Для каждой версии должен быть отдельный раздел. + %li + Одинаковые типы изменений должны быть сгруппированы. + %li + Должна быть возможность поставить ссылку на любую версию или раздел. + %li + Последняя версия должна идти в начале файла. + %li + У каждой версии указана дата выпуска. + %li + Уточните, следуете ли вы принципам #{link_to "Семантического версионирования", semver} - - Люди смогут видеть, какие изменения ожидаются в ближайших релизах - - В момент релиза вам нужно всего лишь заменить секцию `Unreleased` на номер - версии и добавить новую секцию `Unreleased` в начале файла. + %a.anchor{ href: "#types", aria_hidden: "true" } + %h4#types Типы изменений - ### Что заставляет плакать единорогов? - Хорошо… давайте разберёмся. + %ul + %li + %code Добавлено + для новых функций. + %li + %code Изменено + для изменений в существующей функциональности. + %li + %code Устарело + для функций, которы скоро будут удалены. + %li + %code Удалено + для удалённых функций. + %li + %code Исправлено + для любых исправлений. + %li + %code Безопасность + в случае уязвимостей. - - **Выгрузка изменений лога коммитов.** Просто не делайте так, это никому не - принесёт пользы. - - **Отсутствие отметок планируемой к удалению функциональности.** Когда люди - обновляются от одной версии к другой, им должно быть очевидно до боли, что - сломается. - - **Даты в местном формате.** В Соединённых Штатах, люди сначала пишут месяц - («06-02-2012» для даты 2 июня 2012, что не имеет *никакого* смысла), хотя - много людей в остальном мире пишет роботоподобное «2 июня 2012», всё ещё - произнося это по-другому. «2012-06-02» логично работает от самого большого - к самому маленькому, не пересекается с другими форматами дат, и является - [стандартом ISO](http://www.iso.org/iso/home/standards/iso8601.htm). Таким - образом, этот формат является рекомендуемым для логов изменений. +.effort - Существуют и другие. Помогите мне собрать слёзы единорогов, - [открыв тикет][issues] или пулл-реквест. + %h3#effort + %a.anchor{ href: "#effort", aria_hidden: "true" } + Как мне тратить меньше усилий на ведение лога изменений? - ### Существует стандарт формата лога изменений? - К сожалению, нет. Спокойней. Я знаю, что вы яростно бросились на поиски - ссылки на GNU-руководства по стилю лога изменений, или на поиски файла - «guideline» с парой параграфов в GNU NEWS. GNU-руководство по стилю неплохо - для начала, но оно наивно. В наивности нет ничего плохого, но когда людям - нужно руководство, она редко бывает полезна. Особенно, когда приходиться - сталкиваться со множеством краевых случаев. + %p + Ведите раздел Новое с изменениями для новой версии в начале файла. - Этот проект [содержит информацию, которая, я надеюсь, станет соглашением - получше о ведении файлов CHANGELOG][CHANGELOG] для всех проектов с открытым - исходным кодом. Может ли сообщество учиться на своих ошибках, а не просто - действовать согласно десяти записям, которые были написаны много лет назал, - и, якобы, без одной ошибки? Хорошо. Поэтому, пожалуйста, посмотрите вокруг, и - помните, что [обсуждения и предложения по улучшению приветствуются][issues]! + %p Это нужно для двух вещей: - ### Как можно назвать файл лога изменений? - Ну, если вы не не можете ответить на этот вопрос, глядя на пример выше, - `CHANGELOG.md` пока наилучший вариант. + %ul + %li + Люди смогут видеть, каких изменений им ожидать в ближайших релизах + %li + В момент релиза вы можете переместить изменения раздела Новое + в раздел нового релиза. - Некоторые проекты используют `HISTORY.txt`, `HISTORY.md`, `History.md`, - `NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, - `releases.md`, и так далее. +.bad-practices + %h3#bad-practices + %a.anchor{ href: "#bad-practices", aria_hidden: "true" } + Бывают плохие логи изменений? - Это непорядок. Все эти имена только усложняют поиск нужного файла. + %p Да. Вот несколько способов чтобы сделать их не такими полезными. - ### Почему люди не могут использовать просто дифф команды `git log`? - Потому, что диффы логов по своей природе содержат слишком много «шума». С их - помощью невозможно сделать подходящий лог изменений даже в гипотетическом - проекте, который делается идеальными программистами, которые никогда не - делают опечаток, никогда не забывают коммитить новые файлы, никогда не - пропускают ни одну часть рефакторинга. Назначение коммита в том, чтобы - задокументировать один атомарный шаг в процессе развития кода от одного - состояния к другому. Назначение лога изменений – документировать значимые - различия между этими состояниями. + %h4#log-diffs + %a.anchor{ href: "#log-diffs", aria_hidden: "true" } + Диффы лога коммитов - Как отличаются хорошие комментарии к коду и сам код, также отличаются друг от - друга и лог изменений с логом коммитов: первые отвечают на вопрос - *почему*, а вторые на вопрос как. + %p + Использование диффов лога коммитов это плохая идея: они очень шумные. + Шумят мердж-коммиты, коммиты с непонятными названиями, изменения в документации + и тому подобное. - ### Могут ли логи изменений быть автоматически распарсены? - Это сложно из-за того, что люди следуют сильно отличающимся форматам и - соглашениям о именах файлов. + %p + Назначение коммита в том, чтобы задокументировать шаг в эволюции исходного + кода. В некоторых проектах следят за историей коммитов, в некоторых нет. - Гем для Руби [Vandamme][vandamme], который создали в команде - [Gemnasium][gemnasium], парсит многие (но не все) логи изменений проектов с - открытым исходным кодом. + %p + Назначение же раздела в логе изменений — задокументировать ключевые различия, + часто между несколькими коммитами, чтобы ясно донести их назначение + до конечных пользователей. - ### Почему вы пишите то «CHANGELOG», то «лог изменений»? - «CHANGELOG» – это имя файла. Оно несколько крикливо, но это историческое - соглашение, которому следуют многие проекты с открытым исходным кодом. В - качестве примеров подобных файлов можно привести [`README`][README], - [`LICENSE`][LICENSE], и [`CONTRIBUTING`][CONTRIBUTING]. - Верхний регистр в имени файла (который в старых операционных системах - заставляет эти файлы находиться наверху списков) используется для привлечения - внимания. Так как в этих файлах содержится важная метаинформация о проекте, - они могут быть полезны любому использующему или дорабатывющему проект, также - как [бейджи проектов с открытым исходным кодом][shields]. + %h4#ignoring-deprecations + %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } + Игнорирование устаревающих функций - Когда я упоминаю «лог изменений», я говорою о назначении этого файла: об - учёте изменений. + %p + Когда люди обновляются с одной версии на другую, должно быть до боли + очевидно, что сломается. Должна быть возможность обновиться до версии, которая + перечисляет устаревающие функции, удалить устаревшие данные, затем обновиться до версии, + в которой устаревающие функции становятся удалёнными. - ### Как насчёт yanked-релизов? - Yanked-релизы – это версии, которые изымаются из обращения из-за серьёзного - бага или проблемы безопасности в них. Часто такие версии даже не упоминаются - в логах изменений. А должны. И вот как вам следует их упоминать: + %p + Если вы не ведёте лог изменений, то хотя бы указывайте в нём устаревающие + и удалённые функции, а также все критичные изменения. - `## 0.0.5 - 2014-12-13 [YANKED]` + %h4#confusing-dates + %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } + Непонятные даты - Тег `[YANKED]` такой «громкий» не просто так. Очень важно, чтобы люди его - заметили. А из-за того, что он окружён скобками, его легче определить - программно. + %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" } + Часто задаваемые вопросы - ### Как я могу помочь вашему проекту? - Этот документ **не истина в последней инстанции**; это моё тщательно - сформулированное мнение вместе с информацией и примерами, которые я собрал. - Хотя я предоставил настоящий [CHANGELOG][] из [GitHub-репозитария][gh], я - специально избегал цели создать *стандарт* или чёткий список правил (как это - делает, например, [SemVer.org][semver]). + %h4#standard + %a.anchor{ href: "#standard", aria_hidden: "true" } + Существует ли стандарт формата логов изменений? - Я сделал это потому, что хочу, чтобы наше сообщество достигло консенсуса. Я - верю, что дискуссия также важна, как и её результат. + %p + На самом деле нет. Есть стайлгайд логов изменений GNU, + есть длиной-в-два-параграфа файл "guideline" GNU NEWS. + Оба или неадекватны или недостаточно полны. - Так что, пожалуйста, [**участвуйте**][gh]. + %p + Цель этого проекта — стать + = link_to "улучшенной версией соглашения о формате логов изменений.", changelog + Это приходит из-за сбора и следования хорошим практикам сообщества. - [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/ + %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}, + чтобы поговорить о том, почему мейнтейнеры и контрьбьюторы долны вести логи изменений, + а также о моей мотивации к созданию этого проекта.