mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-08-21 17:58:15 +02:00
bee0534514
Previously they had to be duplicated from the page frontmatter but that's not necessary and also makes it possible to have correct OpenGraph title and descriptions.
292 lines
13 KiB
Plaintext
292 lines
13 KiB
Plaintext
---
|
||
title: Ведіть Changelog
|
||
description: Не дозволяйте друзям зливати логи гіта у лог змін.
|
||
language: uk
|
||
version: 1.0.0
|
||
---
|
||
.header
|
||
.title
|
||
%h1= current_page.data.title
|
||
%h2= current_page.data.description
|
||
|
||
= 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}. Тому такий формат рекомендується для
|
||
логів змін.
|
||
|
||
%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}, щоб обговорити
|
||
те, чому ментейнери та контриб'ютори повинні вести логи змін, а також
|
||
про мою мотивацію для створення цього проекту.
|