---
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"
- 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/"

.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} это гем для Руби, созданный командой
    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},
    чтобы поговорить о том, почему мейнтейнеры и контрьбьюторы должны вести логи изменений,
    а также о моей мотивации к созданию этого проекта.