Improve the Russian translation (#408)

This commit is contained in:
edukisto 2021-08-17 19:37:59 +03:00 committed by GitHub
parent 457f11501c
commit 2d00c59f2f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -14,11 +14,13 @@ version: 1.0.0
- vandamme = "https://github.com/tech-angels/vandamme/" - vandamme = "https://github.com/tech-angels/vandamme/"
- iso = "http://www.iso.org/iso/home/standards/iso8601.htm" - iso = "http://www.iso.org/iso/home/standards/iso8601.htm"
- ghr = "https://help.github.com/articles/creating-releases/" - 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 .header
.title .title
%h1 Ведите CHANGELOG %h1 Ведите changelog
%h2 Не позволяйте друзьям сливать логи гита в CHANGELOG™ %h2 Не позволяйте друзьям сливать логи Git в changelogи.
= link_to changelog do = link_to changelog do
Version Version
@ -32,25 +34,26 @@ version: 1.0.0
Что такое лог изменений? Что такое лог изменений?
%p %p
Лог изменений это файл, который содержит поддерживаемый, хронологически Лог изменений это файл, который содержит поддерживаемый, хронологически
упорядоченный список изменений для каждой версии проекта. упорядоченный список значимых изменений для каждой версии проекта.
%h3#why %h3#why
%a.anchor{ href: "#why", aria_hidden: "true" } %a.anchor{ href: "#why", aria_hidden: "true" }
Зачем вести лог изменений? Зачем вести лог изменений?
%p %p
Чтобы пользователям и контрибьюторам было проще точно понять, Чтобы пользователям и контрибуторам было проще в точности понять,
какие изменения были сделаны в каждом релизе (или версии) проекта какие значимые изменения были внесены в каждый выпуск (или версию)
проекта.
%h3#who %h3#who
%a.anchor{ href: "#who", aria_hidden: "true" } %a.anchor{ href: "#who", aria_hidden: "true" }
Кому нужен лог изменений? Кому нужен лог изменений?
%p %p
Людям. Будь то клиенты или разработчики, конечные пользователи программного обеспечения Людям. Конечные пользователи программного обеспечения, будь то клиенты или разработчики, —
это люди, и им важно, с чем они работают. Когда программное обеспечение меняется, это человеческие существа, которым небезразлично, с чем они работают. Когда
люди хотят знать почему и что изменилось. программное обеспечение изменяется, люди хотят знать, что и почему изменилось.
.good-practices .good-practices
%h3#how %h3#how
@ -59,23 +62,23 @@ version: 1.0.0
%h4#principles %h4#principles
%a.anchor{ href: "#principles", aria_hidden: "true" } %a.anchor{ href: "#principles", aria_hidden: "true" }
Главные принципы Руководящие принципы
%ul %ul
%li %li
Лог изменений ведётся <em>для людей</em>, не для машин. Лог изменений — <em>для людей</em>, а не для машин.
%li %li
Для каждой версии должен быть отдельный раздел. Для каждой версии без исключения следует создать отдельный раздел.
%li %li
Одинаковые типы изменений должны быть сгруппированы. Однотипные изменения следует группировать.
%li %li
Должна быть возможность поставить ссылку на любую версию или раздел. Следует предусмотреть возможность поставить ссылку на любую версию или раздел.
%li %li
Последняя версия должна идти в начале файла. Последняя версия должна идти в начале файла.
%li %li
У каждой версии указана дата выпуска. Указаны даты выпуска каждой версии.
%li %li
Уточните, следуете ли вы принципам #{link_to "Семантического версионирования", semver} Уточните, следуете ли вы принципам #{link_to "семантического версионирования", semver}.
%a.anchor{ href: "#types", aria_hidden: "true" } %a.anchor{ href: "#types", aria_hidden: "true" }
%h4#types Типы изменений %h4#types Типы изменений
@ -83,22 +86,22 @@ version: 1.0.0
%ul %ul
%li %li
%code Добавлено %code Добавлено
для новых функций. для новых функций.
%li %li
%code Изменено %code Изменено
для изменений в существующей функциональности. для изменений в существующей функциональности.
%li %li
%code Устарело %code Устарело
для функций, которые скоро будут удалены. для функций, которые скоро будут удалены.
%li %li
%code Удалено %code Удалено
для удалённых функций. для удалённых на данный момент функций.
%li %li
%code Исправлено %code Исправлено
для любых исправлений. для любых исправлений багов.
%li %li
%code Безопасность %code Безопасность
в случае уязвимостей. — на случай уязвимостей.
.effort .effort
@ -107,72 +110,79 @@ version: 1.0.0
Как мне тратить меньше усилий на ведение лога изменений? Как мне тратить меньше усилий на ведение лога изменений?
%p %p
Ведите раздел <code>Новое</code> с изменениями для новой версии в начале файла. Держите в начале файла раздел <code>Новое</code>, позволяющий отслеживать
предстоящие изменения.
%p Это нужно для двух вещей: %p Это служит достижению двух целей:
%ul %ul
%li %li
Люди смогут видеть, каких изменений им ожидать в ближайших релизах люди смогут видеть, каких изменений им можно ожидать в предстоящих выпусках;
%li %li
В момент релиза вы можете переместить изменения раздела <code>Новое</code> в момент релиза вы можете переместить изменения из раздела <code>Новое</code>
в раздел нового релиза. в раздел нового выпуска.
.bad-practices .bad-practices
%h3#bad-practices %h3#bad-practices
%a.anchor{ href: "#bad-practices", aria_hidden: "true" } %a.anchor{ href: "#bad-practices", aria_hidden: "true" }
Бывают плохие логи изменений? Бывают ли плохие логи изменений?
%p Да. Вот несколько способов чтобы сделать их не такими полезными. %p Да. Вот несколько причин, по которым они могут оказаться совершенно бесполезными.
%h4#log-diffs %h4#log-diffs
%a.anchor{ href: "#log-diffs", aria_hidden: "true" } %a.anchor{ href: "#log-diffs", aria_hidden: "true" }
Диффы лога коммитов Diffы лога коммитов
%p %p
Использование диффов лога коммитов это плохая идея: они очень шумные. Использование diffов лога коммитов в качестве лога изменений — это плохая идея:
Шумят мердж-коммиты, коммиты с непонятными названиями, изменения в документации они полны информационного шума от слияния коммитов, от коммитов с непонятными
и тому подобное. заглавиями, от изменений в документации и т. п.
%p %p
Назначение коммита в том, чтобы задокументировать шаг в эволюции исходного Назначение коммита в том, чтобы задокументировать шаг в эволюции исходного
кода. В некоторых проектах следят за историей коммитов, в некоторых нет. кода. В некоторых проектах следят за историей коммитов, в некоторых нет.
%p %p
Назначение же раздела в логе изменений — задокументировать ключевые различия, Назначение же раздела в логе изменений — задокументировать заслуживающие
часто между несколькими коммитами, чтобы ясно донести их назначение внимания различия (зачастую привнесённые несколькими коммитами), чтобы чётко
до конечных пользователей. сообщить конечным пользователям об этих различиях.
%h4#ignoring-deprecations %h4#ignoring-deprecations
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
Игнорирование устаревающих функций Игнорирование устаревших функций
%p %p
Когда люди обновляются с одной версии на другую, должно быть до боли Когда люди переходят с одной версии на другую, им должно быть до боли ясно,
очевидно, что сломается. Должна быть возможность обновиться до версии, которая в какой именно момент что-то сломается. Следует предусмотреть возможность
перечисляет устаревающие функции, удалить устаревшие данные, затем обновиться до версии, перейти к версии, в которой перечислены устаревшие функции, удалить то,
в которой устаревающие функции становятся удалёнными. что устарело, а затем перейти к версии, из которой эти устаревшие функции
удалены.
%p %p
Если вы не ведёте лог изменений, то хотя бы указывайте в нём устаревающие Перечисляйте в логе изменений устаревшие и удалённые функции, а также любые
и удалённые функции, а также все критичные изменения. критические изменения, даже если не перечисляете ничего другого.
%h4#confusing-dates %h4#confusing-dates
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" } %a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
Непонятные даты Даты, сбивающие с толку
%p %p
В США сначала пишут месяц (<code>06-02-2012</code> для 2 июня 2012), Региональные форматы дат различаются по всему миру, и зачастую трудно найти
в то время как большинство людей в остальном мире пишут роботоподобное удобный для человека формат, который был бы интуитивно понятен каждому.
<code>2 июня 2012</code>, произнося эту дата по-разному. Запись Преимущество дат в форматах наподобие <code>2017-07-17</code> заключается
<code>2012-06-02</code> логично идёт от большего к меньшему, не пересекается в том, что элементы в них следуют в порядке от более крупной единицы измерения
с большинством других форматов дат, и является #{link_to "стандартом ISO", iso}. к более мелкой: год, месяц и день. К тому же, в отличие от некоторых
Поэтому именно такой формат рекомендуется для логов изменений. региональных форматов, в которых изменено положение чисел, обозначающих день
и месяц, этот формат не пересекается с другим и не вызывает неоднозначных
толкований. Исходя из этих причин и того факта, что этот формат соответствует
#{link_to "стандарту ISO", iso}, именно он рекомендован для записей в логе
изменений.
%aside %aside
Есть и другие. Помогите мне собрать эти антипаттерны, Есть кое-что ещё. Помогите мне собрать эти антипаттерны,
#{link_to "создав тикет", "#issues"} или пулл-реквест. сделав #{link_to "заявку о наличии проблемы", "#issues"}
или pull request.
.frequently-asked-questions .frequently-asked-questions
%h3#frequently-asked-questions %h3#frequently-asked-questions
@ -181,21 +191,22 @@ version: 1.0.0
%h4#standard %h4#standard
%a.anchor{ href: "#standard", aria_hidden: "true" } %a.anchor{ href: "#standard", aria_hidden: "true" }
Существует ли стандарт формата логов изменений? Существует ли стандартный формат для логов изменений?
%p %p
На самом деле нет. Есть стайлгайд логов изменений GNU, На самом деле, нет. Есть #{link_to "стилистический путеводитель по логам изменений от GNU", gnustyle},
есть длиной-в-два-параграфа файл "guideline" GNU NEWS. есть «руководство» #{link_to "длиной в два абзаца по файлам GNU NEWS", gnunews}.
Оба или неадекватны или недостаточно полны. Оба или неадекватны, или недостаточно полны.
%p %p
Цель этого проекта — стать Этот проект нацелен на то, чтобы стать
= link_to "улучшенной версией соглашения о формате логов изменений.", changelog #{link_to "улучшенной версией соглашения о формате логов изменений", changelog}.
Это приходит из-за сбора и следования хорошим практикам сообщества. Проект опирается на отслеживание и накопление передового опыта сообщества
пользователей открытого исходного кода.
%p %p
Здоровая критика, дискуссии и предложения по улучшению Здоровая критика, дискуссии и предложения по улучшению
= link_to "приветствуются.", issues #{link_to "приветствуются", issues}.
%h4#filename %h4#filename
@ -203,65 +214,66 @@ version: 1.0.0
Как назвать файл лога изменений? Как назвать файл лога изменений?
%p %p
Назовите его <code>CHANGELOG.md</code>. Некоторые проекты также используют Назовите его <code>CHANGELOG.md</code>. Некоторые проекты используют
<code>HISTORY</code>, <code>NEWS</code> или <code>RELEASES</code>. <code>HISTORY</code>, <code>NEWS</code> или <code>RELEASES</code>.
%p %p
Хоть и легко подумать, что имя файла лога изменений не так уж и важно, Хотя легко подумать, что имя файла лога изменений не имеет большого значения,
но зачем усложнять вашим конечным пользователям поиск места, зачем усложнять вашим конечным пользователям поиск места,
где описаны все ключевые изменения? в котором описаны все значимые изменения?
%h4#github-releases %h4#github-releases
%a.anchor{ href: "#github-releases", aria_hidden: "true" } %a.anchor{ href: "#github-releases", aria_hidden: "true" }
Что насчёт функции "Релизы" на Гитхабе? Что насчёт функции «Релизы» на GitHubе?
%p %p
Это отличная инициатива. #{link_to "Релизы", ghr} могут использоваться Это отличная инициатива. #{link_to "Релизы", ghr} можно использовать
для превращения простых тегов в Git (например, тег <code>v1.0.0</code>) для превращения простых тегов Git (например, тега, названного <code>v1.0.0</code>)
в подробные заметки к релизам с помощью их редактирования вручную, в подробные примечания к выпускам, вручную добавляя эти примечания, или же
или с помощью комментариев к таким тегам. можно извлечь сообщения из аннотированных тегов Git и превратить их в примечания.
%p %p
Релизы на Гитхабе создают непереносимый лог изменений, который может Релизы на GitHubе создают непортируемый лог изменений, который может
быть показан пользователям только на самом Гитхабе. Возможно вести быть показан пользователям только на самом GitHubе. Возможно вести его в формате,
их в формате, близком к формату проекта Keep a Changelog, но это требует очень похожем на формат проекта Keep a Changelog, но это, как правило,
больших усилий. немного сложнее.
%p %p
Текущая версия Релизов на Гитхабе также возможно не так хорошо видна Также возможно, что конечным пользователям не всегда легко обнаружить
для конечных пользователей, в отличие от обычных файлов с именами в верхнем текущую версию GitHub Releases, в отличие от обычных файлов с именами в верхнем
регистре (<code>README</code>, <code>CONTRIBUTING</code> и так далее). регистре (<code>README</code>, <code>CONTRIBUTING</code> и т. д.).
Другая небольшая проблема заключается в том, что интерфейс не предлагает Другая небольшая проблема заключается в том, что в настоящее время
ссылок на логи коммитов между релизами. интерфейс не предлагает ссылок на логи коммитов, выполненных между релизами.
%h4#automatic %h4#automatic
%a.anchor{ href: "#automatic", aria_hidden: "true" } %a.anchor{ href: "#automatic", aria_hidden: "true" }
Могут ли логи изменений быть автоматически распарсены? Могут ли логи изменений быть автоматически распарсены?
%p %p
Это сложно, потому что люди следуют сильно различающимся форматам Это сложно, потому что люди соблюдают сильно различающиеся форматы
и используют разные имена файлов. и используют разные имена файлов.
%p %p
#{link_to "Vandamme", vandamme} это гем для Руби, созданный командой #{link_to "Vandamme", vandamme} — это gem для Ruby, созданный командой
Gemnasium, который парсит многие (но не все) Gemnasium и способный парсить многие (но не все)
логи изменений проектов с открытым исходным кодом. логи изменений проектов с открытым исходным кодом.
%h4#yanked %h4#yanked
%a.anchor{ href: "#yanked", aria_hidden: "true" } %a.anchor{ href: "#yanked", aria_hidden: "true" }
Что насчёт yanked-релизов? Что насчёт yanked-выпусков?
%p %p
Yanked-релизы это версии, которые изымаются из обращения из-за серьёзного Yanked-выпуски — это версии, которые пришлось изъять из обращения из-за
бага или проблемы безопасности в них. Часто такие версии даже не упоминаются серьёзного бага или проблем с безопасностью. Часто такие версии даже
в логах изменений. А должны. И вот как вам следует их упоминать: не обозначают в логах изменений. А следовало бы. И вот как вам следует их
обозначать:
%p <code>## [0.0.5] - 2014-12-13 [YANKED]</code> %p <code>## [0.0.5] - 2014-12-13 [YANKED]</code>
%p %p
Тег <code>[YANKED]</code> так бросается в глаза специально. Очень важно, Тег <code>[YANKED]</code> так бросается в глаза неспроста. Очень важно,
чтобы люди его заметили. Так как он обрамлён квадратными скобками, чтобы люди его заметили. Поскольку он заключён в квадратные скобки,
его также проще распарсить программно. его также проще распарсить программно.
@ -271,25 +283,26 @@ version: 1.0.0
%p %p
Конечно. Всегда есть веские причины для улучшения лога изменений. Конечно. Всегда есть веские причины для улучшения лога изменений.
Я регулярно открываю пулл-реквесты по добавлению недостающих релизов Я регулярно подаю pull requestы на добавление недостающих выпусков в проекты
в проекты с открытым исходным кодом с брошенными логами изменений. с открытым исходным кодом, которые оставили свои логи изменений без сопровождения.
%p %p
Также возможно вы можете обнаружить, что вы забыли указать критичное Возможно, вы обнаружите, что забыли указать критичное
изменение в замечаниям к версии. В этом случае очевидно вам важно изменение в примечании к версии. Очевидно, что в этом случае вам важно
обновить ваш лог изменений. обновить ваш лог изменений.
%h4#contribute %h4#contribute
%a.anchor{ href: "#contribute", aria_hidden: "true" } %a.anchor{ href: "#contribute", aria_hidden: "true" }
Как я могу помочь вашему проекту? Как я могу помочь вашему проекту?
%p %p
Этот документ <strong>не истина в последней инстанции</strong>; это моё Этот документ <strong>не истина в последней инстанции</strong>; это моё
тщательно обдуманное мнение, вместе с информацией и примерами, которые я собрал. тщательно обдуманное мнение наряду с информацией и примерами, которые я собрал.
%p %p
Дело в том, что я хочу, чтобы наше сообщество достигло согласия в этом вопросе. Дело в том, что я хочу, чтобы наше сообщество пришло к согласованному мнению.
Я верю, что дискуссия также важна, как и конечный результат. Я верю, что дискуссия так же важна, как и конечный результат.
%p %p
Так что, пожалуйста, <strong>#{link_to "участвуйте", gh}</strong>. Так что, пожалуйста, <strong>#{link_to "участвуйте", gh}</strong>.
@ -297,6 +310,6 @@ version: 1.0.0
.press .press
%h3 Обсуждения %h3 Обсуждения
%p %p
Я приходил в #{link_to "подкаст The Changelog", thechangelog}, Я приходил на #{link_to "подкаст The Changelog", thechangelog}, чтобы поговорить о том,
чтобы поговорить о том, почему мейнтейнеры и контрьбьюторы должны вести логи изменений, почему maintainerам (персоналу сопровождения) и контрибуторам следует озаботиться
а также о моей мотивации к созданию этого проекта. ведением логов изменений, а также о мотивах, стоящих за этим проектом.