mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-28 16:24:07 +02:00
Add the Russian translation of v1.1.0 (#410)
This commit is contained in:
edukisto
GitHub
parent
2eb5b2924f
commit
457f11501c
329
source/ru/1.1.0/index.html.haml
Normal file
329
source/ru/1.1.0/index.html.haml
Normal file
@ -0,0 +1,329 @@
|
|||||||
|
---
|
||||||
|
description: Keep a Changelog
|
||||||
|
title: Keep a Changelog
|
||||||
|
language: ru
|
||||||
|
version: 1.1.0
|
||||||
|
---
|
||||||
|
|
||||||
|
- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/main/CHANGELOG.md"
|
||||||
|
- gh = "https://github.com/olivierlacan/keep-a-changelog"
|
||||||
|
- issues = "https://github.com/olivierlacan/keep-a-changelog/issues"
|
||||||
|
- semver = "https://semver.org/"
|
||||||
|
- shields = "https://shields.io/"
|
||||||
|
- thechangelog = "https://changelog.com/podcast/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/"
|
||||||
|
- gnustyle = "https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs"
|
||||||
|
- gnunews = "https://www.gnu.org/prep/standards/html_node/NEWS-File.html#NEWS-File"
|
||||||
|
|
||||||
|
.header
|
||||||
|
.title
|
||||||
|
%h1 Ведите changelog
|
||||||
|
%h2 Не позволяйте друзьям сливать логи Git в 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" }
|
||||||
|
Diff’ы лога коммитов
|
||||||
|
|
||||||
|
%p
|
||||||
|
Использование diff’ов лога коммитов в качестве лога изменений — это плохая идея:
|
||||||
|
они полны информационного шума от слияния коммитов, от коммитов с непонятными
|
||||||
|
заглавиями, от изменений в документации и т. п.
|
||||||
|
|
||||||
|
%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>2017-07-17</code> заключается
|
||||||
|
в том, что элементы в них следуют в порядке от более крупной единицы измерения
|
||||||
|
к более мелкой: год, месяц и день. К тому же, в отличие от некоторых
|
||||||
|
региональных форматов, в которых изменено положение чисел, обозначающих день
|
||||||
|
и месяц, этот формат не пересекается с другим и не вызывает неоднозначных
|
||||||
|
толкований. Исходя из этих причин и того факта, что этот формат соответствует
|
||||||
|
#{link_to "стандарту ISO", iso}, именно он рекомендован для записей в логе
|
||||||
|
изменений.
|
||||||
|
|
||||||
|
%h4#inconsistent-changes
|
||||||
|
%a.anchor{ href: "#inconsistent-changes", aria_hidden: "true" }
|
||||||
|
Непоследовательные изменения
|
||||||
|
|
||||||
|
%p
|
||||||
|
Лог изменений, в котором упомянуты только некоторые изменения, может быть опасен
|
||||||
|
в той же мере, что и отсутствие лога изменений. Несмотря на то, что многие изменения
|
||||||
|
могут не иметь отношения к делу (например, не во всех случаях может потребоваться
|
||||||
|
регистрировать удаление одного пробела), в логе следует упоминать любые важные
|
||||||
|
изменения. Применяя изменения непоследовательно, ваши пользователи могут ошибочно
|
||||||
|
считать лог изменений единственным источником истины. Таким он и должен быть.
|
||||||
|
С большой силой приходит большая ответственность — наличие хорошего лога изменений
|
||||||
|
означает наличие последовательно обновляемого лога изменений.
|
||||||
|
|
||||||
|
%aside
|
||||||
|
Есть кое-что ещё. Помогите мне собрать эти антипаттерны,
|
||||||
|
сделав #{link_to "заявку о наличии проблемы", "#issues"}
|
||||||
|
или pull request.
|
||||||
|
|
||||||
|
.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
|
||||||
|
На самом деле, нет. Есть #{link_to "стилистический путеводитель по логам изменений от GNU", gnustyle},
|
||||||
|
есть «руководство» #{link_to "длиной в два абзаца по файлам GNU NEWS", gnunews}.
|
||||||
|
Оба или неадекватны, или недостаточно полны.
|
||||||
|
|
||||||
|
%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" }
|
||||||
|
Что насчёт функции «Релизы» на GitHub’е?
|
||||||
|
|
||||||
|
%p
|
||||||
|
Это отличная инициатива. #{link_to "Релизы", ghr} можно использовать
|
||||||
|
для превращения простых тегов Git (например, тега, названного <code>v1.0.0</code>)
|
||||||
|
в подробные примечания к выпускам, вручную добавляя эти примечания, или же
|
||||||
|
можно извлечь сообщения из аннотированных тегов Git и превратить их в примечания.
|
||||||
|
|
||||||
|
%p
|
||||||
|
Релизы на GitHub’е создают непортируемый лог изменений, который может
|
||||||
|
быть показан пользователям только на самом GitHub’е. Возможно вести его в формате,
|
||||||
|
очень похожем на формат проекта Keep a Changelog, но это, как правило,
|
||||||
|
немного сложнее.
|
||||||
|
|
||||||
|
%p
|
||||||
|
Также возможно, что конечным пользователям не всегда легко обнаружить
|
||||||
|
текущую версию GitHub Releases, в отличие от обычных файлов с именами в верхнем
|
||||||
|
регистре (<code>README</code>, <code>CONTRIBUTING</code> и т. д.).
|
||||||
|
Другая небольшая проблема заключается в том, что в настоящее время
|
||||||
|
интерфейс не предлагает ссылок на логи коммитов, выполненных между релизами.
|
||||||
|
|
||||||
|
%h4#automatic
|
||||||
|
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
||||||
|
Могут ли логи изменений быть автоматически распарсены?
|
||||||
|
|
||||||
|
%p
|
||||||
|
Это сложно, потому что люди соблюдают сильно различающиеся форматы
|
||||||
|
и используют разные имена файлов.
|
||||||
|
|
||||||
|
%p
|
||||||
|
#{link_to "Vandamme", vandamme} — это gem для Ruby, созданный командой
|
||||||
|
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
|
||||||
|
Конечно. Всегда есть веские причины для улучшения лога изменений.
|
||||||
|
Я регулярно подаю pull request’ы на добавление недостающих выпусков в проекты
|
||||||
|
с открытым исходным кодом, которые оставили свои логи изменений без сопровождения.
|
||||||
|
|
||||||
|
%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}, чтобы поговорить о том,
|
||||||
|
почему maintainer’ам (персоналу сопровождения) и контрибуторам следует озаботиться
|
||||||
|
ведением логов изменений, а также о мотивах, стоящих за этим проектом.
|
||||||
Loading…
x
Reference in New Issue
Block a user