diff --git a/source/ru/1.0.0/index.html.haml b/source/ru/1.0.0/index.html.haml deleted file mode 100644 index 1c6c2c6..0000000 --- a/source/ru/1.0.0/index.html.haml +++ /dev/null @@ -1,197 +0,0 @@ ---- -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/