Ведіть Changelog

Не дозволяйте друзям зливати логи гіта у лог змін.

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- v1.1 Brazilian Portuguese translation.
- v1.1 German Translation
- v1.1 Spanish translation.
- v1.1 Italian translation.
- v1.1 Polish translation.
- v1.1 Ukrainian translation.

### Changed

- Use frontmatter title & description in each language version template
- Replace broken OpenGraph image with an appropriately-sized Keep a Changelog 
  image that will render properly (although in English for all languages)
- Fix OpenGraph title & description for all languages so the title and 
description when links are shared are language-appropriate

### Removed

- Trademark sign previously shown after the project description in version 
0.3.0

## [1.1.1] - 2023-03-05

### Added

- Arabic translation (#444).
- v1.1 French translation.
- v1.1 Dutch translation (#371).
- v1.1 Russian translation (#410).
- v1.1 Japanese translation (#363).
- v1.1 Norwegian Bokmål translation (#383).
- v1.1 "Inconsistent Changes" Turkish translation (#347).
- Default to most recent versions available for each languages.
- Display count of available translations (26 to date!).
- Centralize all links into `/data/links.json` so they can be updated easily.

### Fixed

- Improve French translation (#377).
- Improve id-ID translation (#416).
- Improve Persian translation (#457).
- Improve Russian translation (#408).
- Improve Swedish title (#419).
- Improve zh-CN translation (#359).
- Improve French translation (#357).
- Improve zh-TW translation (#360, #355).
- Improve Spanish (es-ES) transltion (#362).
- Foldout menu in Dutch translation (#371).
- Missing periods at the end of each change (#451).
- Fix missing logo in 1.1 pages.
- Display notice when translation isn't for most recent version.
- Various broken links, page versions, and indentations.

### Changed

- Upgrade dependencies: Ruby 3.2.1, Middleman, etc.

### Removed

- Unused normalize.css file.
- Identical links assigned in each translation file.
- Duplicate index file for the english version.

## [1.1.0] - 2019-02-15

### Added

- Danish translation (#297).
- Georgian translation from (#337).
- Changelog inconsistency section in Bad Practices.

### Fixed

- Italian translation (#332).
- Indonesian translation (#336).

## [1.0.0] - 2017-06-20

### Added

- New visual identity by [@tylerfortune8](https://github.com/tylerfortune8).
- Version navigation.
- Links to latest released version in previous versions.
- "Why keep a changelog?" section.
- "Who needs a changelog?" section.
- "How do I make a changelog?" section.
- "Frequently Asked Questions" section.
- New "Guiding Principles" sub-section to "How do I make a changelog?".
- Simplified and Traditional Chinese translations from [@tianshuo](https://github.com/tianshuo).
- German translation from [@mpbzh](https://github.com/mpbzh) & [@Art4](https://github.com/Art4).
- Italian translation from [@azkidenz](https://github.com/azkidenz).
- Swedish translation from [@magol](https://github.com/magol).
- Turkish translation from [@emreerkan](https://github.com/emreerkan).
- French translation from [@zapashcanon](https://github.com/zapashcanon).
- Brazilian Portuguese translation from [@Webysther](https://github.com/Webysther).
- Polish translation from [@amielucha](https://github.com/amielucha) & [@m-aciek](https://github.com/m-aciek).
- Russian translation from [@aishek](https://github.com/aishek).
- Czech translation from [@h4vry](https://github.com/h4vry).
- Slovak translation from [@jkostolansky](https://github.com/jkostolansky).
- Korean translation from [@pierceh89](https://github.com/pierceh89).
- Croatian translation from [@porx](https://github.com/porx).
- Persian translation from [@Hameds](https://github.com/Hameds).
- Ukrainian translation from [@osadchyi-s](https://github.com/osadchyi-s).

### Changed

- Start using "changelog" over "change log" since it's the common usage.
- Start versioning based on the current English version at 0.3.0 to help
  translation authors keep things up-to-date.
- Rewrite "What makes unicorns cry?" section.
- Rewrite "Ignoring Deprecations" sub-section to clarify the ideal
  scenario.
- Improve "Commit log diffs" sub-section to further argument against
  them.
- Merge "Why can’t people just use a git log diff?" with "Commit log
  diffs".
- Fix typos in Simplified Chinese and Traditional Chinese translations.
- Fix typos in Brazilian Portuguese translation.
- Fix typos in Turkish translation.
- Fix typos in Czech translation.
- Fix typos in Swedish translation.
- Improve phrasing in French translation.
- Fix phrasing and spelling in German translation.

### Removed

- Section about "changelog" vs "CHANGELOG".

## [0.3.0] - 2015-12-03

### Added

- RU translation from [@aishek](https://github.com/aishek).
- pt-BR translation from [@tallesl](https://github.com/tallesl).
- es-ES translation from [@ZeliosAriex](https://github.com/ZeliosAriex).

## [0.2.0] - 2015-10-06

### Changed

- Remove exclusionary mentions of "open source" since this project can
  benefit both "open" and "closed" source projects equally.

## [0.1.0] - 2015-10-06

### Added

- Answer "Should you ever rewrite a change log?".

### Changed

- Improve argument against commit logs.
- Start following [SemVer](https://semver.org) properly.

## [0.0.8] - 2015-02-17

### Changed

- Update year to match in every README example.
- Reluctantly stop making fun of Brits only, since most of the world
  writes dates in a strange way.

### Fixed

- Fix typos in recent README changes.
- Update outdated unreleased diff link.

## [0.0.7] - 2015-02-16

### Added

- Link, and make it obvious that date format is ISO 8601.

### Changed

- Clarified the section on "Is there a standard change log format?".

### Fixed

- Fix Markdown links to tag comparison URL with footnote-style links.

## [0.0.6] - 2014-12-12

### Added

- README section on "yanked" releases.

## [0.0.5] - 2014-08-09

### Added

- Markdown links to version tags on release headings.
- Unreleased section to gather unreleased changes and encourage note
  keeping prior to releases.

## [0.0.4] - 2014-08-09

### Added

- Better explanation of the difference between the file ("CHANGELOG")
  and its function "the change log".

### Changed

- Refer to a "change log" instead of a "CHANGELOG" throughout the site
  to differentiate between the file and the purpose of the file — the
  logging of changes.

### Removed

- Remove empty sections from CHANGELOG, they occupy too much space and
  create too much noise in the file. People will have to assume that the
  missing sections were intentionally left out because they contained no
  notable changes.

## [0.0.3] - 2014-08-09

### Added

- "Why should I care?" section mentioning The Changelog podcast.

## [0.0.2] - 2014-07-10

### Added

- Explanation of the recommended reverse chronological release ordering.

## [0.0.1] - 2014-05-31

### Added

- This CHANGELOG file to hopefully serve as an evolving example of a
  standardized open source project CHANGELOG.
- CNAME file to enable GitHub Pages custom domain.
- README now contains answers to common questions about CHANGELOGs.
- Good examples and basic guidelines, including proper date formatting.
- Counter-examples: "What makes unicorns cry?".

[unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.1...HEAD
[1.1.1]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.0...v1.1.1
[1.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0
[0.3.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.8...v0.1.0
[0.0.8]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.7...v0.0.8
[0.0.7]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.6...v0.0.7
[0.0.6]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.5...v0.0.6
[0.0.5]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.4...v0.0.5
[0.0.4]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.3...v0.0.4
[0.0.3]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.2...v0.0.3
[0.0.2]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.1...v0.0.2
[0.0.1]: https://github.com/olivierlacan/keep-a-changelog/releases/tag/v0.0.1

Що таке лог змін?

Лог змін - це файл, що містить підтримуваний та хронологічно впорядкований список змін для кожної версії проекту.

Навіщо вести лог змін?

Це дозволяє полегшити користувачам та контриб'юторам слідкувати за змінами у релізах (чи версіях) проекту.

Кому потрібен лог змін?

Людям. Користувачам та розробникам, кінцевими користувачами програмного забезпечення є люди, яким важливо знати з чим вони працюють. Якщо відбулися змін, то люди повинні знати що змінилося і як.

Як створити хороший лог змін?

Головні принципи

Лог змін для людей, а не машин.
Окремий розділ для кожної версії.
Зміни одного типу мають бути згруповані.
На версії та секції потрібно ставити гіперпосилання.
Остання версія мусить бути на початку.
Кожна версія має мати власну дату.
Вкажіть чи підтримуєте Ви принципи Семантичне версіювання.

Типи змін

Додано для нового функціоналу.
Змінено для змін в існуючий функціонал.
Застаріло для функціоналу, що планується видалити.
Видалено про вже видалений функціонал.
Виправлення для будь яких виправлень.
Безпека при виявленні вразливостей.

Як мені докладати мінімальні зусилля для ведення логу змін?

Ведіть розділ Нове на початку файла.

Для переслідування подвійної цілі:

Люди можуть бачити майбутні зміни в найближчому релізі
Як настане час релізу, Ви можете перемістити розділ Нове у розділ нового релізу,

Чи може лог змін бути поганим?

Так. Ось декілька способів зробити лог змін не вдалим.

Логи змін між комітами.

Використовувати логи комітів як логи змін - це погана ідея. Вони наповнені інформаційним шумом. Такими як коміти злиття, не інформативні назви комітів, змінами у документації тощо.

Призначення комітів у тому, щоб документувати кроки в еволюції коду. У деяких проектах історія комітів доглянута, в інших - ні.

Призначення ж логу змін полягає у документації вагомих змін, часто між багатьма комітами, доносячи їх призначення до кінцевого користувача.

Ігнорування застарілого функціоналу

Коли люди оновлюються з версії до версії, їм потрібна повна впевненість у тому, чи може щось зламатися. Їм повинна бути надана можливість оновитися до версії зі списком застарілого функціоналу, видалити все застаріле, а потім оновитися до версії з видаленим застарілим функціоналом.

Якщо Ви не займаєтеся логом змін, то хоча б ведіть список застарілого, видаленого або серйозних змін функціоналу.

Незрозумілі дати

Регіональні дати можуть відрізнятися і це може бути складно для правильного розуміння ваших дат для користувачів у різних куточках світу. Варто надавати переваги датам, що форматовані за таким зразком: 2017-07-17. У них числа ідуть від найбільшого до найменшого: рік, місяць, день. Мінімізує конфузи у випадку використання регіональних форматів, коли день і місяць можуть мати різний порядок. Цей формат не пересікається з більшістю інших форматів і є стандартом ISO. Тому такий формат рекомендується для логів змін.

Невідповідність змінам

Журнал змін, у якому згадуються лише деякі зміни, може становити таку ж небезпеку як і відсутність журналу змін. Незважаючи на те, що багато змін можуть бути незначними (наприклад, видалення одного пробілу може не потребувати сповіщення), будь-які важливі зміни слід згадувати в журналі змін. Застосовуючи зміни непослідовно ваші користувачі можуть помилково подумати, що журнал змін є єдиним джерелом правди. І так має бути. Сила тут походить від відповідальності — мати хороший журнал змін означає постійно оновлювати журнал змін.

Поширені запитання

Чи існує стандарт логів змін?

Не зовсім. Є стайлгайд логів змін GNU або довгий у два параграфа GNU NEWS file. Обидва неадекватні і неповні.

Цей проект покликаний бути поліпшеною угодою про логи змін. Це виходить із ліпших практик open source спільноти.

Здорова критика, дискусія та пропозиції поліпшення вітаються.

Як назвати файл логів змін?

Назвіть CHANGELOG.md. У деяких проектах файл носить назви HISTORY, NEWS або RELEASES.

Може видатися, що назва файлу для логів змін не суттєва, проте навіщо ускладнювати життя користувачам змушуючи їх шукати?

Як щодо GitHub релізів?

Це чудова ініціатива. Релізи можуть бути використані для перетворення простих тегів у Git (v1.0.0 - до прикладу) у деталізовані нотатки до релізів шляхом їх редагування вручну або за допомогою коментарів до цих тегів.

Релізи GitHub є не портативним логом змін, який може бути показаний користувачам лише на самому сайті GitHub. Його можна вести подібно до формату Keep a Changelog, але для цього потрібні значні зусилля.

Поточна версія на GitHub не так добре очевидна для користувача, на відмінну від звичайних файлів з іменами у верхньому регістрі (README, CONTRIBUTING і так далі). Крім того, інтерфейс не дозволяє посилання на логи комітів між релізами.

Чи можуть логи змін автоматично парситися?

Це заскладно, оскільки люди використовують різні формати та імена файлів.

Vandamme - це гем для Ruby, створений командою Gemnasium, який парсить багато (але не всі) логи змін проектів з відкритим кодом.

А як щодо yanked-релізів?

Yanked-релізи - це версії, що вилучаються із-за серйозних багів або проблем з безпекою у них. Часто вони навіть не згадуються у логах змін. А повинні. І описуватися вони повинні так:

## [0.0.5] - 2014-12-13 [YANKED]

[YANKED] навмисне кидається в очі. Важливо, щоб його помітили. Обмежений квадратними дужками, щоб його легше було спарсити.

Чи є сенс переписати лог змін?

Звісно. Завжди є сенс поліпшувати лог змін. І відкривати пул-реквести додаючи втрачені релізи у проекти з відкритим кодом і закинутими логами змін.

Також можлива ситуація, що Ви забули вказати критичні зміни для версії. Очевидно, що потрібно такий лог оновити.

Як я можу допомогти вашому проекту?

Цей документ не претендує на виключну правду; Це моє бачення, зі зібраною інформацію та прикладами.

Хотів би, щоб спільнота дійшла згоди. Я вірю у дискусію та результат.

Тому беріть участь.

Обговорення

Я приходив на підкаст The Changelog, щоб обговорити те, чому ментейнери та контриб'ютори повинні вести логи змін, а також про мою мотивацію для створення цього проекту.