Changelog

Changelog на одному екрані — готовий

Більшість тих, хто шукає changelog, хоче побачити хороший. Ось один — для невеликої бібліотеки всередині інтернет-магазину, що проходить крізь сторінки розділів «Декомпозиція» і «Процес релізу». orders-client — пакет, через який чотири команди читають замовлення: вебмагазин, консоль підтримки, листи-підтвердження замовлень і нічне вивантаження для аналітики. Кожна команда сама вирішує, коли оновлюватися, — і саме для такого читача існує changelog. На екран уміщається лише частина файлу: шапка, розділ Unreleased і чотири версії. Наступні розділи посилаються на рядки за номерами.

1. 1.Шапка — що це за файл і що він обіцяє

   1. 1.1Усі помітні зміни orders-client записано тут, найновіші першими. Формат — Keep a Changelog 1.1.0
   2. 1.2Версії відповідають Semantic Versioning 2.0.0. Публічний APIAPIApplication Programming Interface — контракт між програмамиПравила, за якими одна програма звертається до іншої: які запити можна надіслати, у якому вигляді й що прийде у відповідь. Для того, хто звертається, це контракт — усе, що за ним, лишається чорною скринькою, і саме тому другий бік можна переписати, не зламавши вас.Докладніше в статті →Усі терміни — те, що перелічено в docs/api.md: експортовані функції, поля повернених об’єктів і коди помилок. Усе інше може змінитися в будь-якому релізі
   3. 1.3Політика депрекації: усе задепрековане працює до наступної мажорної версії — і щонайменше шість місяців після релізу, який це задепрекував

2. 2.[Unreleased]

   1. 2.1Added — order.reorderSource: history, saved-basket або null — звідки почали повторне замовлення. У замовлень, оформлених до 20 жовтня, завжди null
   2. 2.2Deprecated — getOrders({ customerId }). Використовуйте getCustomerOrders(customerId) з рядка 3.1. Буде видалено в 3.0.0 — і не раніше ніж через шість місяців після цього релізу. Виклик пише одне попередження на процес, а ендпоінт за ним відповідає заголовками Deprecation і Sunset

3. 3.[2.7.0] — 2026-09-15

   1. 3.1Added — getCustomerOrders(customerId), що проходить сторінками історію будь-якої довжини. getOrders мовчки зупинявся на 100 замовленнях
   2. 3.2Added — address.postcode з тим самим значенням, що й address.zip
   3. 3.3Deprecated — address.zip. Читайте натомість address.postcode. zip лишається до 3.0.0 і щонайменше до 15 березня 2027 року; перше читання в процесі пише попередження
   4. 3.4Security — email клієнта більше не потрапляє в debug-лог (DEBUG=orders-client). Оновіться негайно, якщо debug-логування хоч раз вмикали в production

4. 4.[2.6.2] — 2026-08-27

   1. 4.1Fixed — order.placedAt знову в UTCUTCCoordinated Universal Time — світовий еталонний часСтандарт часу, у якому зазвичай ведуть годинники й логи, — без часових поясів і переходу на літній час. Він додає високосні секунди, щоб не відставати від обертання Землі, тому час GPS, який цього не робить, нині випереджає його на 18 секунд.Усі терміни, як і задокументовано. 2.6.1 повертала локальний час сервера

5. 5.[2.6.1] — 2026-08-26 [YANKED]

   1. 5.1Fixed — order.total тепер враховує знижку за ваучером. Не використовуйте цю версію: вона ще й перевела placedAt на локальний час, і 212 пізніх вечірніх замовлень потрапили в нічному вивантаженні не в той день. Відкликано наступного ранку; використовуйте 2.6.2

6. 6.[2.0.0] — 2026-03-02

   1. 6.1Removed — getOrderLines(orderId). Рядки замовлення тепер в order.lines. Див. «Перехід на 2.0», крок 1
   2. 6.2Changed — гроші тепер ціле число найменших одиниць валюти: total: 4999, а не "49.99". Кожне місце, що форматує чи додає ціни, треба змінити. Див. «Перехід на 2.0», крок 2

7. 7.Посилання

   1. 7.1Кожен заголовок версії веде на свій diff — [2.7.0]: …/compare/v2.6.2...v2.7.0, — а [Unreleased] порівнює останній тег із main

Git log — не changelog, і реліз-ноти теж

Слово має два значення, і це половина плутанини. GNU Coding Standards вимагають файл ChangeLog, що фіксує кожну зміну кожного файлу коду, — щоб «ті, хто розслідуватиме баги в майбутньому», могли їх простежити. Нині стандарти приймають замість нього журнал системи контролю версій. Ті самі стандарти вимагають другий файл, NEWS: «перелік видимих користувачеві змін, вартих згадки», найновіші першими. Те, що Keep a Changelog називає changelog, — це другий файл під назвою першого. Олів’є Лакан уперше опублікував цю конвенцію 2014 року, і вона визначає документ як «впорядкований хронологічний перелік помітних змін для кожної версії проєкту».

Прочитайте праву колонку очима однієї з чотирьох команд-споживачів. Ніщо в ній не каже, що zip зникне, — а це єдине, що створює роботу. Третій коміт — виправлення безпеки, записане як звичайний fix. А останні два взагалі нічого не кажуть нікому поза командою.

Чотири документи, чотири читачі

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

Реліз повторного замовлення зі сторінки про планування релізу дає три з них. Рядок 2.1 вище — рядок changelog для чотирьох команд-споживачів. Клієнти натомість отримують реліз-ноту: «Повторіть минуле замовлення з історії двома дотиками. Усе, чого немає в наявності, названо — з пропозицією заміни». Це рядок 1.4 плану релізу. А коли 3.0.0 прибере zip, гайд з міграції отримає крок зі старим читанням, новим читанням і пошуком, що знаходить кожне використання, яке лишилося.

Номер версії — це обіцянка

Semantic Versioning перетворює три числа на контракт сумісності. Його написав Том Престон-Вернер; версію 1.0.0 специфікації позначили тегом у вересні 2011 року, а 2.0.0, чинну досі, — у червні 2013-го. MAJOR зростає за несумісних змін публічного API, MINOR — за нової зворотно сумісної функціональності, PATCH — за зворотно сумісних виправлень. Річ не в охайності. Читач може вирішити, чи безпечне оновлення, не читаючи diff, а менеджер пакетів може вирішити це замість нього.

Правило, на якому все тримається: якщо наявним користувачам треба щось змінити, щоб усе далі працювало, це підняття MAJOR — хай яким дрібним це здається зсередини. Перейменування поля, суворіша валідація, обов’язковий параметр замість необов’язкового і зміна значення за замовчуванням — усе це ламкі зміни. Випустити одну з них патчем — саме так залежність заробляє собі репутацію.

Нуль, пререлізи та метадані збірки

Усе, що починається з 0, явно поза обіцянкою: під час 0.y.z, каже пункт 4, «будь-що МОЖЕ змінитися будь-коли». Це чесно, поки дизайн ще рухається, і нечесно, коли від нього вже залежать. FAQ самої специфікації каже прямо: «Якщо вашою програмою користуються в production, вона, ймовірно, вже має бути 1.0.0». Проєкт, що чотири роки сидить на 0.x зі споживачами в production, використовує нуль, щоб уникнути зобов’язання.

Пререліз позначають дефісом — 3.0.0-rc.1 — і він сортується перед релізом, якому передує, тож менеджер пакетів, що просить 3.0.0 чи вище, не візьме його випадково. Метадані збірки позначають плюсом — 3.0.0+build.482 — і при порівнянні версій їх повністю ігнорують. Тож це правильне місце для хешу коміту й неправильне — для будь-чого, що треба знати користувачеві. А випущену версію ніколи не змінюють: якщо 2.6.1 виявилася зламаною, виправлення — це 2.6.2, а 2.6.1 лишається у файлі з позначкою, як у групі 5.

Контракт — і все інше, від чого залежать люди

SemVer може обіцяти лише те, що каже публічний API. Гайрам Райт, тоді в Google, сформулював проблему одним реченням, яке Тайтус Вінтерс згодом назвав законом Гайрама: «Коли в API достатньо користувачів, неважливо, що ви обіцяєте в контракті: від кожної помітної поведінки вашої системи хтось залежатиме». Порядок результатів, тривалість виклику, точне формулювання помилки — чийсь код це читає.

Менеджери пакетів роблять це гострішим. У npm залежність, записана як ^2.6.0, приймає будь-яку 2.x.y від 2.6.0 і вище, тож нова minor-версія доходить до кожного споживача на наступному чистому встановленні — і ніхто перед тим не читає changelog. Lockfilelockfileточні версії кожної залежностіФайл, який менеджер пакетів пише поряд зі списком залежностей і в якому записано точну версію кожного встановленого пакета — зокрема тих, що підтягнули ваші залежності. Закомічений у репозиторій, він робить кожне встановлення однаковим; без нього дві збірки того самого коміту можуть виконувати різний код.Усі терміни тримає стару версію, доки її хтось не оновить, — це відкладає сюрприз, але не скасовує його. Тому MINOR, що щось ламає, розходиться далі й швидше, ніж будь-коли зміг би MAJOR.

Інші схеми нумерації — і що обіцяє кожна

Схема Stripe варта другого погляду, бо відповідає на питання, яке SemVer лишає споживачеві: коли я беру ламку зміну? Кожен акаунт закріплено за версією API, що була чинною, коли він почав роботу, а запит може попросити іншу заголовком Stripe-Version. До 2017 року Stripe так випустила «майже сотню зворотно несумісних оновлень», нікого не зламавши без його згоди. Починаючи з 2024-09-30.acacia, щомісячні версії не мають ламких змін, а мажорний реліз із ламкими змінами виходить двічі на рік.

Як написати запис, за яким можна діяти

Keep a Changelog групує кожен реліз під шістьма заголовками. Однакові шість скрізь означають, що читач може одразу шукати потрібний — зазвичай Removed і Changed, бо саме вони створюють роботу.

Решта конвенції механічна, і її варто дотримуватися точно, бо саме вона дозволяє читачеві щось знайти. Її керівні принципи: changelog — для людей, а не для машин; запис для кожної версії без винятку; зміни одного типу згруповано; на версії й розділи можна послатися; найновіша версія — першою; дату релізу кожної версії показано; і сказано, чи дотримується проєкт Semantic Versioning. Дати — за ISO 8601: 2026-09-15, а не 15/09/26, що читається як два різні дні залежно від країни читача. Розділ Unreleased стоїть угорі, а відкликана версія лишається у файлі з гучною позначкою [YANKED].

Вісім записів, як їх пишуть команди, — і переписані

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

Депрекація — те, що купує довіру

Removed — заголовок, що створює роботу; Deprecated — заголовок, що дає людям час її зробити. Депрекація — це обіцянка з трьох частин, а повідомлення без будь-якої з них є скаргою на власний код.

• Що зникає — названо достатньо точно, щоб читач міг пошукати це у власному коді: address.zip, а не «старі поля адреси».
• Що використовувати натомість — і заміна доступна вже, а не обіцяна на потім: рядок 3.2 випустив postcode у тому самому релізі, що задепрекував zip.
• Коли це прибиратимуть — версією й найранішою датою, а не порою року: «3.0.0 і не раніше 15 березня 2027 року».

SemVer вбудовує цю послідовність. Пункт 7 каже, що minor-реліз МУСИТЬ вийти, коли щось публічне позначають задепрекованим, а FAQ просить «щонайменше один minor-реліз, що містить депрекацію», перед мажорним, який її прибирає. Keep a Changelog формулює мету з боку читача: «Має бути можливо оновитися до версії, яка перелічує депрекації, прибрати задепрековане, а тоді оновитися до версії, де депрекації стали видаленнями». Рядок 1.3 додає нижню межу в часі, бо споживач, що оновлюється двічі на рік, інакше може зустріти депрекацію й видалення за один крок.

Депрекація HTTP-ендпоінта

Ендпоінт за рядком 2.2, GET /orders?customer=, може казати про це в кожній відповіді. Deprecation: @1789430400 дає момент депрекації, 15 вересня 2026 року, у секундах Unix після @. Sunset: Mon, 15 Mar 2027 00:00:00 GMT дає найраніший момент, коли він може перестати відповідати, — у старішому форматі HTTP-date. Заголовок Link з rel="deprecation" веде на сторінку з поясненням переходу. RFCRFCRequest for Comments — нумерований стандарт інтернетуНумерований документ, який публікує IETF — організація, що стандартизує інтернет-протоколи; HTTP, TLS і JSON визначено саме в RFC. Опублікований RFC ніколи не змінюється — виправлення виходить новим RFC з новим номером, тому «RFC 9110» називає один точний текст.Усі терміни 9745 додає два правила, які варто знати. Депрекація «не змінює жодної поведінки ресурсу», а дата Sunset не може бути ранішою за дату Deprecation.

Заголовок позначає ресурс, а не поле, тож рядок 3.3 він оголосити не може. Про address.zip повідомляють changelog і документація, а бібліотека пише попередження, коли процес уперше його читає. Саме з цього попередження команда й дізнається, хто досі від нього залежить.

Як далеко чесно заходить автоматизація

Conventional Commits 1.0.0, опублікована 2019 року й виросла з конвенції комітів проєкту Angular, стандартизує перший рядок повідомлення коміту так, щоб його міг прочитати інструмент: тип, необов’язкова область, необов’язковий ! для ламкої зміни, далі опис — «feat(address): add postcode», «fix!: require a currency on every price». Ламку зміну можна також оголосити у футері, що починається з BREAKING CHANGE:, і це краще місце, коли потрібне речення пояснення. Інші типи, крім feat і fix, дозволені і, за специфікацією, «не мають неявного впливу на Semantic Versioning».

Це справді допомагає. Інструмент може вивести наступний номер версії й зібрати чернетку під правильними заголовками, а це два найнудніші кроки. Чого він не може — вирішити, чи є зміна ламкою, бо це залежить від того, як люди користуються продуктом, а це знання живе поза репозиторієм. Коміт із міткою fix:, що змінює значення за замовчуванням, є ламким, — а інструмент цілком упевнено назве його патчем.

Останні два відповідають на проблеми, які порушили попередні розділи. Запис пише той, хто розуміє зміну, поки вона свіжа, і його переглядають у тому самому pull requestpull requestзміна, запропонована на рев’юЗапит на злиття однієї гілки в іншу, де зміну переглядають, обговорюють і перевіряють пайплайном, перш ніж вона потрапить у головну гілку; у GitLab те саме зветься merge request. Його ціна — очікування: pull request, що днями чекає на рев’ю, і породжує довгоживучі гілки та болісні злиття.Докладніше в статті →Усі терміни, що й код, — тож рецензент, який бачить зміну значення за замовчуванням, бачить і рядок, що називає її патчем. А оскільки кожна зміна приносить власний файл, немає єдиного CHANGELOG.md, який редагує кожна гілка і на якому конфліктує кожне злиття. README towncrier пояснює причину прямо: він доносить новини так, як «зручно тим, хто їх чує, а не тим, хто їх пише».

Чотири релізи, де проблемою був рядок changelog

Кожен кейс нижче задокументував сам проєкт. У жодному з них код не був усією історією. Щоразу не дійшло до читача число, рядок чи сигнал, які мали б дійти.

is-promise, 2020 — minor, що був major

is-promise — бібліотека в один рядок: функція, що каже, чи є значення промісом. За тиждень до 25 квітня 2020 року її завантажили близько 11,7 мільйона разів — майже завжди як залежність чогось іншого. Того дня о 15:03 UTC мейнтейнер опублікував 2.2.0, перший реліз із вересня 2015-го. Він додав точку входу ES-модуля — "type": "module" і мапу exports у package.json, — і мапа виявилася хибною. Кожен проєкт, що залежав від ^2.1.0, отримав новий minor на наступному чистому встановленні. Свіжовстановлені Create React App, інструмент командного рядка Angular та інструменти Firebase перестали працювати.

2.2.1 вийшла о 17:55, а 2.2.2, уже без exports, — о 18:08: загалом близько трьох годин. Найкорисніше тут — коментар самого мейнтейнера в issue: «Я прочитав документацію, а тоді зробив цю зміну, вважаючи її доволі безпечною». Наступного дня ту саму зміну exports, уже правильно сформовану, опублікували знову — як 3.0.0. Зміна способу завантаження пакета є частиною його публічного API, і число має це казати.

Kubernetes 1.16, 2019 — два роки попереджень, яких ніхто не бачив

Kubernetes 1.16, випущений 18 вересня 2019 року, перестав обслуговувати Deployment, DaemonSet, StatefulSet і ReplicaSet зі старих версій API extensions/v1beta1 та apps/v1beta1/v1beta2. Заміна, apps/v1, була доступна з v1.9, грудень 2017 року. Депрекація була в реліз-нотах, а в липні проєкт опублікував допис-попередження про видалення. Маніфести й Helm-чарти, досі написані під старі версії, після оновлення однаково падали.

Відповідь проєкту у v1.19 (2020) перенесла попередження туди, де працює код. Кожен запит до задепрекованого API тепер повертає заголовок-попередження, який друкує kubectl, з назвою релізу, що перестане його обслуговувати, і заміною. Метрика apiserver_requested_deprecated_apis показує адміністраторам, які задепрековані API досі викликають. Це попередження на процес і заголовок Sunset з рядка 2.2 — у масштабі цілої екосистеми.

dockershim, 2020 — правильний рядок, прочитаний хибно

Реліз-ноти v1.20 у грудні 2020 року задепрекували dockershim — адаптер, через який kubelet використовував Docker Engine як середовище виконання контейнерів. Рядок був точним. Його прочитали як «Kubernetes відмовляється від Docker», і те, що проєкт згодом назвав панікою, перетворилося на «пожежу в соцмережах». Більшості читачів це взагалі не стосувалося, бо образи, зібрані Docker, працюють у кожному середовищі. Проєкт написав «Don’t Panic: Kubernetes and Docker» і FAQ. 2022 року, коли v1.24 прибрав адаптер, допис проєкту сказав прямо: «Ми погано про це повідомили… Це була наша провина».

Рядок changelog був правильним документом для операторів кластерів. Усім іншим потрібен був інший документ — реліз-ноти, що кажуть, кого це стосується, а кого ні, — і він з’явився вже після того, як рядок прочитали хибно. Коли депрекація зачіпає назву, яку люди впізнають, пишіть цей другий документ першим.

Log4j, 2021 — заголовок Security під тиском

CVECVECommon Vulnerabilities and Exposures — публічний номер відомої вразливостіПублічний ідентифікатор відомої вади безпеки, як-от CVE-2021-44228 для Log4Shell, щоб постачальники, сканери й бюлетені мали на увазі той самий баг. Номер каже, що вада існує; наскільки вона небезпечна саме для вас, залежить від того, чи працює у вас уражена версія і чи відкрита назовні вражена частина.Усі терміни-2021-44228 у Log4j 2 з оцінкою 10,0 дозволяла віддалене виконання коду через рядок, що потрапляв у лог. Версія 2.15.0 з’явилася в Maven Central 9 грудня 2021 року. Далі виявилися нові проблеми, а слідом вийшли 2.16.0 13 грудня, 2.17.0 18 грудня і 2.17.1 27 грудня — кожна «безпечна версія» до наступної. Старші гілки Java отримали власні виправлення: 2.12.x для Java 7 і 2.3.x для Java 6. Три тижні команди по всьому світу знову й знову відкривали одну сторінку, щоб відповісти на два питання: чи це мене стосується і на що переходити?

Сторінка безпеки Apache Logging відповідає на них у сталій формі для кожної вразливості: уражений діапазон, виправлена версія для кожної гілки Java і пом’якшення для тих, хто не може оновитися. Саме такої форми, у меншому масштабі, потребує запис Security. Рядок 3.4 каже, що витікало, за якого налаштування і кому оновлюватися. «Виправлення безпеки» не відповіло б на жодне з двох питань.

Де він вироджується — і чого changelog не може

Перевірка changelog — чи відкриває його хтось під тиском. Після оновлення о 16:40 щось зламалося, і людина, яка ніколи не читала вашого коду, відкриває файл. Менш ніж за хвилину вона має з’ясувати, чи змінила версія, на яку вона перейшла, те, що в неї перед очима. Усе в конвенції — найновіше вгорі, шість сталих заголовків, рядок на зміну, наслідки замість правок — існує, щоб зробити цю хвилину можливою. Ось як вона стає неможливою.

• Згенероване вивантаження комітів, опубліковане без редагування, — його ніхто не читає двічі.
• Ламкі зміни, випущені як minor чи patch, — вони витрачають довіру, яку мало нести число.
• Немає оголошеного публічного API — тож будь-який рефакторинг начебто ламкий, і ніхто цього не розрізнить.
• Роки на 0.x зі споживачами в production — нуль, використаний, щоб ухилитися від зобов’язання.
• Депрекації без заміни чи без дати видалення — за ними ніхто нічого не робить, доки видалення не настане.
• Видалення лише за календарем, поки хтось досі цим користується.
• Записи Security, що не кажуть, кого це стосується, — кожному читачеві вони перетворюють день на розслідування.
• Зламану версію видалено замість позначити [YANKED] — і ті, хто її закріпив, не дізнаються, чому вона зникла.

Коли це застосовувати

Пов’язані сторінки

• МенеджментПланування релізуПланування релізу — це рішення про те, що потрапляє до користувачів, коли і як ви дізнаєтесь, що щось пішло не так. Найкорисніший крок у ньому — перестати вважати деплой і реліз однією подією: код потрапляє в production вимкненим, а відкриття доступу стає окремим, зворотним рішенням, яке ухвалюють поетапно. Сторінка починається з готового плану одного релізу; далі — деплой проти релізу, фіксована дата проти фіксованого обсягу, стратегії викочування, чотири види feature flag, шлях назад, чотири релізи, що провалилися, і рядок, якого бракувало кожному, та як вимірювати процес.
• МенеджментGit-стратегія гілкуванняGit-стратегія гілкування — це домовленість про те, як команда розділяє роботу на гілки і як знову їх зводить. Вибір виглядає справою смаку, але нею не є: змінна, що передбачає біль, — скільки живе гілка до злиття, і кожна модель — це позиція щодо цього числа плюс правило, звідки беруться релізи й виправлення. Сторінка починається з шести моделей на одному екрані й п’яти питань, що обирають між ними; далі — час життя гілки, звідки взялася кожна модель і що її автори сказали згодом, релізні гілки й шлях виправлення, що робить короткі гілки можливими, merge проти rebase проти squash і де все це вироджується.
• РозробкаДизайн APIДизайн API — це робота над тим, що інші програми можуть надсилати вашій, що вони отримають у відповідь і які з цих обіцянок ви триматимете роками. Усе, що споживач може спостерегти, стає частиною обіцянки, і забрати її самотужки ви не можете. Сторінка починається з шістнадцяти рішень, які ухвалює кожен HTTP-API, — що обрати за замовчуванням і чого коштує змінити кожне пізніше; далі — що входить у контракт, методи, коди статусу й помилки, поведінка під повторами й навантаженням, хто що може робити, зміна опублікованого API, п’ять задокументованих кейсів і де все це вироджується.