mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-30 09:14:12 +02:00
Merge branch 'aishek-ru-translation'
This commit is contained in:
Olivier Lacan
commit
70011d08f9
@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
|
|||||||
- French translation from @zapashcanon.
|
- French translation from @zapashcanon.
|
||||||
- Brazilian Portugese translation from @aisamu.
|
- Brazilian Portugese translation from @aisamu.
|
||||||
- Polish translation from @amielucha.
|
- Polish translation from @amielucha.
|
||||||
|
- Russian translation from @aishek.
|
||||||
|
|
||||||
### Changed
|
### Changed
|
||||||
- Start using "changelog" over "change log" since it's the common usage.
|
- Start using "changelog" over "change log" since it's the common usage.
|
||||||
|
|||||||
303
source/ru/1.0.0/index.html.haml
Normal file
303
source/ru/1.0.0/index.html.haml
Normal file
@ -0,0 +1,303 @@
|
|||||||
|
---
|
||||||
|
description: Keep a Changelog
|
||||||
|
title: Keep a Changelog
|
||||||
|
language: ru
|
||||||
|
version: 1.0.0
|
||||||
|
---
|
||||||
|
|
||||||
|
- 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/"
|
||||||
|
|
||||||
|
.header
|
||||||
|
.title
|
||||||
|
%h1 Ведите CHANGELOG
|
||||||
|
%h2 Не позволяйте друзьям сливать логи гита в CHANGELOG™
|
||||||
|
|
||||||
|
= link_to changelog do
|
||||||
|
Version
|
||||||
|
%strong= current_page.metadata[:page][:version]
|
||||||
|
|
||||||
|
%pre.changelog= File.read("CHANGELOG.md")
|
||||||
|
|
||||||
|
.answers
|
||||||
|
%h3#what
|
||||||
|
%a.anchor{ href: "#what", aria_hidden: "true" }
|
||||||
|
Что такое лог изменений?
|
||||||
|
|
||||||
|
%p
|
||||||
|
Лог изменений – это файл, который содержит поддерживаемый, хронологически
|
||||||
|
упорядоченный список изменений для каждой версии проекта.
|
||||||
|
|
||||||
|
%h3#why
|
||||||
|
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||||||
|
Зачем вести лог изменений?
|
||||||
|
|
||||||
|
%p
|
||||||
|
Чтобы пользователям и контрибьюторам было проще точно понять,
|
||||||
|
какие изменения были сделаны в каждом релизе (или версии) проекта
|
||||||
|
|
||||||
|
%h3#who
|
||||||
|
%a.anchor{ href: "#who", aria_hidden: "true" }
|
||||||
|
Кому нужен лог изменений?
|
||||||
|
|
||||||
|
%p
|
||||||
|
Людям. Будь то клиенты или разработчики, конечные пользователи программного обеспечения
|
||||||
|
это люди, и им важно, с чем они работают. Когда программное обеспечение меняется,
|
||||||
|
люди хотят знать почему и что изменилось.
|
||||||
|
|
||||||
|
.good-practices
|
||||||
|
%h3#how
|
||||||
|
%a.anchor{ href: "#how", aria_hidden: "true" }
|
||||||
|
Как мне сделать хороший лог изменений?
|
||||||
|
|
||||||
|
%h4#principles
|
||||||
|
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
||||||
|
Главные принципы
|
||||||
|
|
||||||
|
%ul
|
||||||
|
%li
|
||||||
|
Лог изменений ведётся <em>для людей</em>, не для машин.
|
||||||
|
%li
|
||||||
|
Для каждой версии должен быть отдельный раздел.
|
||||||
|
%li
|
||||||
|
Одинаковые типы изменений должны быть сгруппированы.
|
||||||
|
%li
|
||||||
|
Должна быть возможность поставить ссылку на любую версию или раздел.
|
||||||
|
%li
|
||||||
|
Последняя версия должна идти в начале файла.
|
||||||
|
%li
|
||||||
|
У каждой версии указана дата выпуска.
|
||||||
|
%li
|
||||||
|
Уточните, следуете ли вы принципам #{link_to "Семантического версионирования", semver}
|
||||||
|
|
||||||
|
%a.anchor{ href: "#types", aria_hidden: "true" }
|
||||||
|
%h4#types Типы изменений
|
||||||
|
|
||||||
|
%ul
|
||||||
|
%li
|
||||||
|
%code Добавлено
|
||||||
|
для новых функций.
|
||||||
|
%li
|
||||||
|
%code Изменено
|
||||||
|
для изменений в существующей функциональности.
|
||||||
|
%li
|
||||||
|
%code Устарело
|
||||||
|
для функций, которы скоро будут удалены.
|
||||||
|
%li
|
||||||
|
%code Удалено
|
||||||
|
для удалённых функций.
|
||||||
|
%li
|
||||||
|
%code Исправлено
|
||||||
|
для любых исправлений.
|
||||||
|
%li
|
||||||
|
%code Безопасность
|
||||||
|
в случае уязвимостей.
|
||||||
|
|
||||||
|
.effort
|
||||||
|
|
||||||
|
%h3#effort
|
||||||
|
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
||||||
|
Как мне тратить меньше усилий на ведение лога изменений?
|
||||||
|
|
||||||
|
%p
|
||||||
|
Ведите раздел <code>Новое</code> с изменениями для новой версии в начале файла.
|
||||||
|
|
||||||
|
%p Это нужно для двух вещей:
|
||||||
|
|
||||||
|
%ul
|
||||||
|
%li
|
||||||
|
Люди смогут видеть, каких изменений им ожидать в ближайших релизах
|
||||||
|
%li
|
||||||
|
В момент релиза вы можете переместить изменения раздела <code>Новое</code>
|
||||||
|
в раздел нового релиза.
|
||||||
|
|
||||||
|
.bad-practices
|
||||||
|
%h3#bad-practices
|
||||||
|
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||||||
|
Бывают плохие логи изменений?
|
||||||
|
|
||||||
|
%p Да. Вот несколько способов чтобы сделать их не такими полезными.
|
||||||
|
|
||||||
|
%h4#log-diffs
|
||||||
|
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||||||
|
Диффы лога коммитов
|
||||||
|
|
||||||
|
%p
|
||||||
|
Использование диффов лога коммитов это плохая идея: они очень шумные.
|
||||||
|
Шумят мердж-коммиты, коммиты с непонятными названиями, изменения в документации
|
||||||
|
и тому подобное.
|
||||||
|
|
||||||
|
%p
|
||||||
|
Назначение коммита в том, чтобы задокументировать шаг в эволюции исходного
|
||||||
|
кода. В некоторых проектах следят за историей коммитов, в некоторых нет.
|
||||||
|
|
||||||
|
%p
|
||||||
|
Назначение же раздела в логе изменений — задокументировать ключевые различия,
|
||||||
|
часто между несколькими коммитами, чтобы ясно донести их назначение
|
||||||
|
до конечных пользователей.
|
||||||
|
|
||||||
|
|
||||||
|
%h4#ignoring-deprecations
|
||||||
|
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||||
|
Игнорирование устаревающих функций
|
||||||
|
|
||||||
|
%p
|
||||||
|
Когда люди обновляются с одной версии на другую, должно быть до боли
|
||||||
|
очевидно, что сломается. Должна быть возможность обновиться до версии, которая
|
||||||
|
перечисляет устаревающие функции, удалить устаревшие данные, затем обновиться до версии,
|
||||||
|
в которой устаревающие функции становятся удалёнными.
|
||||||
|
|
||||||
|
%p
|
||||||
|
Если вы не ведёте лог изменений, то хотя бы указывайте в нём устаревающие
|
||||||
|
и удалённые функции, а также все критичные изменения.
|
||||||
|
|
||||||
|
%h4#confusing-dates
|
||||||
|
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||||
|
Непонятные даты
|
||||||
|
|
||||||
|
%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" }
|
||||||
|
Часто задаваемые вопросы
|
||||||
|
|
||||||
|
%h4#standard
|
||||||
|
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
||||||
|
Существует ли стандарт формата логов изменений?
|
||||||
|
|
||||||
|
%p
|
||||||
|
На самом деле нет. Есть стайлгайд логов изменений GNU,
|
||||||
|
есть длиной-в-два-параграфа файл "guideline" GNU NEWS.
|
||||||
|
Оба или неадекватны или недостаточно полны.
|
||||||
|
|
||||||
|
%p
|
||||||
|
Цель этого проекта — стать
|
||||||
|
= link_to "улучшенной версией соглашения о формате логов изменений.", changelog
|
||||||
|
Это приходит из-за сбора и следования хорошим практикам сообщества.
|
||||||
|
|
||||||
|
%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},
|
||||||
|
чтобы поговорить о том, почему мейнтейнеры и контрьбьюторы долны вести логи изменений,
|
||||||
|
а также о моей мотивации к созданию этого проекта.
|
||||||
Loading…
x
Reference in New Issue
Block a user