mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-29 08:44:16 +02:00
Added ukrainian localization
This commit is contained in:
Osadchyi Serhii
parent
b95030549d
commit
219658df35
@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [Unreleased]
|
||||
### Added
|
||||
- Ukrainian translation from [@osadchyi-s](https://github.com/osadchyi-s).
|
||||
### Changed
|
||||
- Update and improvement of Polish translation from [@m-aciek](https://github.com/m-aciek).
|
||||
|
||||
|
||||
304
source/uk/1.0.0/index.html.haml
Normal file
304
source/uk/1.0.0/index.html.haml
Normal file
@ -0,0 +1,304 @@
|
||||
---
|
||||
description: Keep a Changelog
|
||||
title: Keep a 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}, щоб обговорити
|
||||
те, чому ментейнери та контриб'ютори повинні вести логи змін, а також
|
||||
про мою мотивацію для створення цього проекту.
|
||||
Loading…
x
Reference in New Issue
Block a user