mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-08-26 04:08:12 +02:00
305 lines
13 KiB
Plaintext
305 lines
13 KiB
Plaintext
---
|
||
description: Ведіть Changelog
|
||
title: Ведіть Changelog
|
||
language: uk
|
||
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/"
|
||
- 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 Не дозволяйте друзям зливати логи гіта у лог змін.
|
||
|
||
= 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>2017-07-17</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
|
||
Не зовсім. Є #{link_to "стайлгайд логів змін GNU", gnustyle}
|
||
або #{link_to "довгий у два параграфа GNU NEWS file", gnunews}.
|
||
Обидва неадекватні і неповні.
|
||
|
||
%p
|
||
Цей проект покликаний бути
|
||
= link_to "поліпшеною угодою про логи змін.", changelog
|
||
Це виходить із ліпших практик open source спільноти.
|
||
|
||
%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> - до прикладу)
|
||
у деталізовані нотатки до релізів шляхом їх редагування вручну або
|
||
за допомогою коментарів до цих тегів.
|
||
|
||
%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", 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 "беріть участь", gh}</strong>.
|
||
|
||
.press
|
||
%h3 Обговорення
|
||
%p
|
||
Я приходив на #{link_to "підкаст The Changelog", thechangelog}, щоб обговорити
|
||
те, чому ментейнери та контриб'ютори повинні вести логи змін, а також
|
||
про мою мотивацію для створення цього проекту.
|