mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-30 01:04:30 +02:00
Add @aishek's RU translation from #66.
This commit is contained in:
Nathaniel Bibler
parent
38878f9d72
commit
5cbdb0119f
@ -4,7 +4,7 @@
|
|||||||
|
|
||||||
# ----- Site ----- #
|
# ----- Site ----- #
|
||||||
|
|
||||||
activate :i18n, langs: [:en, :fr], :mount_at_root => :en
|
activate :i18n, langs: [:en, :ru], :mount_at_root => :en
|
||||||
set :gauges_id, ''
|
set :gauges_id, ''
|
||||||
set :publisher_url, 'https://www.facebook.com/olivier.lacan.5'
|
set :publisher_url, 'https://www.facebook.com/olivier.lacan.5'
|
||||||
set :site_url, 'http://keepachangelog.com'
|
set :site_url, 'http://keepachangelog.com'
|
||||||
|
|||||||
210
source/ru/index.haml
Normal file
210
source/ru/index.haml
Normal file
@ -0,0 +1,210 @@
|
|||||||
|
---
|
||||||
|
description: Ведите Changelog
|
||||||
|
title: Ведите Changelog
|
||||||
|
language: ru
|
||||||
|
---
|
||||||
|
|
||||||
|
:markdown
|
||||||
|
# Ведите CHANGELOG
|
||||||
|
|
||||||
|
## Не позволяйте друзьям сливать логи гита в CHANGELOG™
|
||||||
|
|
||||||
|
### Что такое лог изменений?
|
||||||
|
|
||||||
|
Лог изменений – это файл, который содержит поддерживаемый, упорядоченный в
|
||||||
|
хронологическом порядке список значимых изменений для каждой версии проекта с
|
||||||
|
открытым исходным кодом.
|
||||||
|
|
||||||
|
%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__))
|
||||||
|
|
||||||
|
: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/
|
||||||
Loading…
x
Reference in New Issue
Block a user