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
|
/_site
|
||||||
/.vs
|
/.vs
|
||||||
/.idea
|
/.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 Spanish translation.
|
||||||
- v1.1 Italian translation.
|
- v1.1 Italian translation.
|
||||||
- v1.1 Polish translation.
|
- v1.1 Polish translation.
|
||||||
|
- v1.1 Ukrainian translation.
|
||||||
|
|
||||||
## [1.1.1] - 2023-03-05
|
## [1.1.1] - 2023-03-05
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,7 @@
|
||||||
description: Prowadź Changelog
|
description: Prowadź Changelog
|
||||||
title: Prowadź Changelog
|
title: Prowadź Changelog
|
||||||
language: pl
|
language: pl
|
||||||
version: 1.0.0
|
version: 1.1.0
|
||||||
---
|
---
|
||||||
.header
|
.header
|
||||||
.title
|
.title
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,7 @@
|
||||||
description: Vzdržujte dnevnik sprememb
|
description: Vzdržujte dnevnik sprememb
|
||||||
title: Vzdržujte dnevnik sprememb
|
title: Vzdržujte dnevnik sprememb
|
||||||
language: sl
|
language: sl
|
||||||
version: 1.0.0
|
version: 1.1.0
|
||||||
---
|
---
|
||||||
.header
|
.header
|
||||||
.title
|
.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