---
title: Ведіть Changelog
description: Не дозволяйте друзям зливати логи гіта у лог змін.
language: uk
version: 1.1.0
---
.header
  .title
    %h1= current_page.data.title
    %h2 Не дозволяйте друзям зливати логи гіта у лог змін.

  = link_to data.links.changelog do
    Version
    %strong= current_page.metadata[:page][:version]

  %pre.changelog{ lang: "en" }= 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 "Семантичне версіювання", data.links.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>2017-07-17</code>. У них числа ідуть від найбільшого до
    найменшого: рік, місяць, день. Мінімізує конфузи у випадку використання
    регіональних форматів, коли день і місяць можуть мати різний порядок.
    Цей формат не пересікається з більшістю інших форматів і є
    #{link_to "стандартом ISO", data.links.isodate}. Тому такий формат рекомендується
    для логів змін.

  %h4#inconsistent-changes
    %a.anchor{ href: "#inconsistent-changes", aria_hidden: "true" }
    Невідповідність змінам

  %p
    Журнал змін, у якому згадуються лише деякі зміни, може становити таку ж небезпеку
    як і відсутність журналу змін. Незважаючи на те, що багато змін можуть бути
    незначними (наприклад, видалення одного пробілу може не потребувати сповіщення),
    будь-які важливі зміни слід згадувати в журналі змін. Застосовуючи зміни
    непослідовно ваші користувачі можуть помилково подумати, що журнал змін
    є єдиним джерелом правди. І так має бути. Сила тут походить від відповідальності
    &mdash; мати хороший журнал змін означає постійно оновлювати журнал змін.

  %aside
    Є також інші. Допоможіть зібрати антипатерни,
    = link_to "створіть тікет", data.links.issue
    або пул реквест

.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", data.links.gnustyle}
    або  #{link_to "довгий у два параграфа GNU NEWS file", data.links.gnunews}.
    Обидва неадекватні і неповні.

  %p
    Цей проект покликаний бути
    = link_to "поліпшеною угодою про логи змін.", data.links.changelog
    Це виходить із ліпших практик open source спільноти.

  %p
    Здорова критика, дискусія та пропозиції поліпшення
    = link_to "вітаються.", data.links.issue

  %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 "Релізи", data.links.github_releases} можуть бути використані для
    перетворення простих тегів у Git (<code>v1.0.0</code> - до прикладу)
    у деталізовані нотатки до релізів шляхом їх редагування вручну або
    за допомогою коментарів до цих тегів.

  %p
    Релізи GitHub є не портативним логом змін, який може бути показаний
    користувачам лише на самому сайті GitHub. Його можна вести подібно
    до формату Keep a Changelog, але для цього потрібні значні зусилля.

  %p
    Поточна версія на GitHub не так добре очевидна для користувача,
    на відмінну від звичайних файлів з іменами у верхньому регістрі
    (<code>README</code>, <code>CONTRIBUTING</code> і так далі).
    Крім того, інтерфейс не дозволяє посилання на логи комітів між
    релізами.

  %h4#automatic
    %a.anchor{ href: "#automatic", aria_hidden: "true" }
    Чи можуть логи змін автоматично парситися?

  %p
    Це заскладно, оскільки люди використовують різні формати та
    імена файлів.

  %p
    #{link_to "Vandamme", data.links.vandamme} - це гем для 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
    Звісно. Завжди є сенс поліпшувати лог змін. І відкривати пул-реквести
    додаючи втрачені релізи у проекти з відкритим кодом і закинутими
    логами змін.

  %p
    Також можлива ситуація, що Ви забули вказати критичні зміни для версії.
    Очевидно, що потрібно такий лог оновити.



  %h4#contribute
    %a.anchor{ href: "#contribute", aria_hidden: "true" }
    Як я можу допомогти вашому проекту?

  %p
    Цей документ не претендує на виключну <strong>правду</strong>;
    Це моє бачення, зі зібраною інформацію та прикладами.

  %p
    Хотів би, щоб спільнота дійшла згоди. Я вірю у дискусію та результат.

  %p
    Тому <strong>#{link_to "беріть участь", data.links.repo}</strong>.

.press
  %h3 Обговорення
  %p
    Я приходив на #{link_to "підкаст The Changelog", data.links.thechangelog}, щоб обговорити
    те, чому ментейнери та контриб'ютори повинні вести логи змін, а також
    про мою мотивацію для створення цього проекту.