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/