diff --git a/CHANGELOG.md b/CHANGELOG.md index 0146065..0759ad5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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). diff --git a/source/uk/1.0.0/index.html.haml b/source/uk/1.0.0/index.html.haml new file mode 100644 index 0000000..3da27c9 --- /dev/null +++ b/source/uk/1.0.0/index.html.haml @@ -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 + Лог змін для людей, а не машин. + %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 + Ведіть розділ Нове на початку файла. + + %p Для переслідування подвійної цілі: + + %ul + %li + Люди можуть бачити майбутні зміни в найближчому релізі + %li + Як настане час релізу, Ви можете перемістити розділ Нове + у розділ нового релізу, + +.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 + Регіональні дати можуть відрізнятися і це може бути складно для + правильного розуміння ваших дат для користувачів у різних куточках + світу. Варто надавати переваги датам, що форматовані за таким зразком: + 2017-07-17. У них числа ідуть від найбільшого до + найменшого: рік, місяць, день. Мінімізує конфузи у випадку використання + регіональних форматів, коли день і місяць можуть мати різний порядок. + Цей формат не пересікається з більшістю інших форматів і є + #{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 + Назвіть CHANGELOG.md. У деяких проектах файл носить назви + HISTORY, NEWS або RELEASES. + + %p + Може видатися, що назва файлу для логів змін не суттєва, проте + навіщо ускладнювати життя користувачам змушуючи їх шукати? + + %h4#github-releases + %a.anchor{ href: "#github-releases", aria_hidden: "true" } + Як щодо GitHub релізів? + + %p + Це чудова ініціатива. #{link_to "Релізи", ghr} можуть бути використані для + перетворення простих тегів у Git (v1.0.0 - до прикладу) + у деталізовані нотатки до релізів шляхом їх редагування вручну або + за допомогою коментарів до цих тегів. + + %p + Релізи GitHub є не портативним логом змін, який може бути показаний + користувачам лише на самому сайті GitHub. Його можна вести подібно + до формату Keep a Changelog, але для цього потрібні значні зусилля. + + %p + Поточна версія на GitHub не так добре очевидна для користувача, + на відмінну від звичайних файлів з іменами у верхньому регістрі + (README, CONTRIBUTING і так далі). + Крім того, інтерфейс не дозволяє посилання на логи комітів між + релізами. + + %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 ## 0.0.5 - 2014-12-13 [YANKED] + + %p + [YANKED] навмисне кидається в очі. Важливо, щоб його + помітили. Обмежений квадратними дужками, щоб його легше було + спарсити. + + + %h4#rewrite + %a.anchor{ href: "#rewrite", aria_hidden: "true" } + Чи є сенс переписати лог змін? + + %p + Звісно. Завжди є сенс поліпшувати лог змін. І відкривати пул-реквести + додаючи втрачені релізи у проекти з відкритим кодом і закинутими + логами змін. + + %p + Також можлива ситуація, що Ви забули вказати критичні зміни для версії. + Очевидно, що потрібно такий лог оновити. + + + + %h4#contribute + %a.anchor{ href: "#contribute", aria_hidden: "true" } + Як я можу допомогти вашому проекту? + + %p + Цей документ не претендує на виключну правду; + Це моє бачення, зі зібраною інформацію та прикладами. + + %p + Хотів би, щоб спільнота дійшла згоди. Я вірю у дискусію та результат. + + %p + Тому #{link_to "беріть участь", gh}. + +.press + %h3 Обговорення + %p + Я приходив на #{link_to "підкаст The Changelog", thechangelog}, щоб обговорити + те, чому ментейнери та контриб'ютори повинні вести логи змін, а також + про мою мотивацію для створення цього проекту.