tyler.durden/keep-a-changelog
1
0
Fork 0
mirror of https://github.com/olivierlacan/keep-a-changelog.git synced 2025-09-26 11:19:22 +02:00
Code Issues Packages Projects Releases Wiki Activity

Added correct russian translation.

Browse Source
This commit is contained in:
Alexandr Borisov 2017-06-30 00:01:03 +03:00
parent 1eb09dd801
commit ff42aba1b1
2 changed files with 264 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGELOG.md
View File

@ -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.

420
source/ru/1.0.0/index.html.haml
View File

@ -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
Лог изменений ведётся <em>для людей</em>, не для машин.
%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
Ведите раздел <code>Новое</code> с изменениями для новой версии в начале файла.
Этот проект [содержит информацию, которая, я надеюсь, станет соглашением
получше о ведении файлов CHANGELOG][CHANGELOG] для всех проектов с открытым
исходным кодом. Может ли сообщество учиться на своих ошибках, а не просто
действовать согласно десяти записям, которые были написаны много лет назал,
и, якобы, без одной ошибки? Хорошо. Поэтому, пожалуйста, посмотрите вокруг, и
помните, что [обсуждения и предложения по улучшению приветствуются][issues]!
%p Это нужно для двух вещей:
### Как можно назвать файл лога изменений?
Ну, если вы не не можете ответить на этот вопрос, глядя на пример выше,
`CHANGELOG.md` пока наилучший вариант.
%ul
%li
Люди смогут видеть, каких изменений им ожидать в ближайших релизах
%li
В момент релиза вы можете переместить изменения раздела <code>Новое</code>
в раздел нового релиза.
Некоторые проекты используют `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
В США сначала пишут месяц (<code>06-02-2012</code> для 2 июня 2012),
в то время как большинство людей в остальном мире пишут роботоподобное
<code>2 июня 2012</code>, произнося эту дата по-разному. Запись
<code>2012-06-02</code> логично идёт от большего к меньшему, не пересекается
с большинством других форматов дат, и является #{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
Назовите его <code>CHANGELOG.md</code>. Некоторые проекты также используют
<code>HISTORY</code>, <code>NEWS</code> или <code>RELEASES</code>.
%p
Хоть и легко подумать, что имя файла лога изменений не так уж и важно,
но зачем усложнять вашим конечным пользователям поиск места,
где описаны все ключевые изменения?
%h4#github-releases
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
Что насчёт функции "Релизы" на Гитхабе?
%p
Это отличная инициатива. #{link_to "Релизы", ghr} могут использоваться
для превращения простых тегов в Git (наприме тег <code>v1.0.0</code>)
в подробные заметки к релизам с помощью их редактирования вручную,
или с помощью комментариев к таким тегам.
%p
Релизы на Гитхабе создают непереносимый лог изменений, который может
быть показан пользователям только на самом Гитхабе. Возможно вести
их в формате, близком к формату проекта Keep a Changelog, но это требует
больших усилий.
%p
Текущая версия Релизов на Гитхабе также возможно не так хорошо видна
для конечных пользователей, в отличии от обычных файлов с именами в верхнем
регистре (<code>README</code>, <code>CONTRIBUTING</code>, и так далее).
Другая небольшая проблема заключается в том, что интерфейс не предлагает
ссылок на логи коммитов между релизами.
%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 <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
%p
Тег <code>[YANKED]</code> так бросается в глаза специально. Очень важно,
чтобы люди его заметели. Так как он обрамлён квадратными скобками,
его также проще распарсить программно.
%h4#rewrite
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
Имеет ли смысл переписывать лог изменений?
%p
Конечно. Всегда есть веские причины для улучшения лога изменений.
Я регулярно открываю пулл-реквесты по добавлению недостающих релизов
в проекты с открытым исходным кодом с брошенными логами изменений.
%p
Также возможно вы можете обнаружить, что вы забыли указать критичное
изменение в замечаниям к версии. В этом случае очевидно вам важно
обновить ваш лог изменений.
%h4#contribute
%a.anchor{ href: "#contribute", aria_hidden: "true" }
Как я могу помочь вашему проекту?
%p
Этот документ <strong>не истина в последней инстанции</strong>; это моё
тщательно обдуманное мнение, вместе с информацией и примерами, которые я собрал.
%p
Дело в том, что я хочу, чтобы наше сообщество достигло согласия в этом вопросе.
Я верю, что дискуссия также важна, как и конечный результат.
%p
Так что, пожалуйста, <strong>#{link_to "участвуйте", gh}</strong>.
.press
%h3 Обсуждения
%p
Я приходил в #{link_to "подкаст The Changelog", thechangelog},
чтобы поговорить о том, почему мейнтейнеры и контрьбьюторы долны вести логи изменений,
а также о моей мотивации к созданию этого проекта.