Fix versioning for Polish and Slovenian. Add 1.1.0 for Ukrainian. (#592)
* Fix versioning for Polish and Slovenian. Add 1.1.0 for Ukrainian. * Update ChangeLog
This commit is contained in:
Vitalij Berdinskih
GitHub
parent
45ce45409a
commit
db925931aa
|
|
@ -6,3 +6,6 @@
|
|||
/_site
|
||||
/.vs
|
||||
/.idea
|
||||
|
||||
*~
|
||||
\#*#
|
||||
|
|
|
|||
|
|
@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||
- v1.1 Spanish translation.
|
||||
- v1.1 Italian translation.
|
||||
- v1.1 Polish translation.
|
||||
- v1.1 Ukrainian translation.
|
||||
|
||||
## [1.1.1] - 2023-03-05
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
description: Prowadź Changelog
|
||||
title: Prowadź Changelog
|
||||
language: pl
|
||||
version: 1.0.0
|
||||
version: 1.1.0
|
||||
---
|
||||
.header
|
||||
.title
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
description: Vzdržujte dnevnik sprememb
|
||||
title: Vzdržujte dnevnik sprememb
|
||||
language: sl
|
||||
version: 1.0.0
|
||||
version: 1.1.0
|
||||
---
|
||||
.header
|
||||
.title
|
||||
|
|
|
|||
|
|
@ -0,0 +1,304 @@
|
|||
---
|
||||
description: Ведіть Changelog
|
||||
title: Ведіть Changelog
|
||||
language: uk
|
||||
version: 1.1.0
|
||||
---
|
||||
.header
|
||||
.title
|
||||
%h1 Ведіть Changelog
|
||||
%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
|
||||
Журнал змін, у якому згадуються лише деякі зміни, може становити таку ж небезпеку
|
||||
як і відсутність журналу змін. Незважаючи на те, що багато змін можуть бути
|
||||
незначними (наприклад, видалення одного пробілу може не потребувати сповіщення),
|
||||
будь-які важливі зміни слід згадувати в журналі змін. Застосовуючи зміни
|
||||
непослідовно ваші користувачі можуть помилково подумати, що журнал змін
|
||||
є єдиним джерелом правди. І так має бути. Сила тут походить від відповідальності
|
||||
- мати хороший журнал змін означає постійно оновлювати журнал змін.
|
||||
|
||||
%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}, щоб обговорити
|
||||
те, чому ментейнери та контриб'ютори повинні вести логи змін, а також
|
||||
про мою мотивацію для створення цього проекту.
|
||||
Loading…
Reference in New Issue