Merge branch 'master' of https://github.com/olivierlacan/keep-a-chang…

…elog

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/