Formaty plików changeloga: JSON, YAML czy zwykły Markdown

Większość zespołów zaczyna changelog jako plik Markdown, bo to droga najmniejszego oporu: czytelny w diffie pull requesta, czytelny na GitHubie bez renderowania czegokolwiek, znajomy każdemu, kto kiedykolwiek napisał README. Ten wybór działa dobrze, dopóki coś innego niż człowiek nie musi przeczytać pliku, strona, widżet, podsumowanie mailowe, i wtedy format przestaje być darmowy. Automatyzacja changeloga ogólnie ujmuje wymóg strukturalny, typ, datę, treść i link; to jest o tym, który format pliku faktycznie dostarcza tę strukturę i ile kosztuje do niej dojście przy każdym z nich.

Co jest nie tak ze zwykłym changelogiem w Markdown?

Nic, dopóki coś nie musi sparsować go z powrotem na pola. Nagłówek, data i lista punktowana pod spodem jest trywialna do przeczytania dla człowieka i naprawdę trudna do niezawodnego parsowania, bo Markdown nie ma schematu: data może być w nagłówku, pogrubiona w pierwszej linii, albo w ogóle brakować w starym wpisie, i każdy z tych wariantów to poprawny Markdown, który człowiek czyta poprawnie, a parser nie. Zespoły automatyzujące changelog w Markdown zwykle kończą pisaniem własnego parsera opartego na regexach, który psuje się, gdy formatowanie wpisu choćby lekko odbiegnie od normy, co zdarza się często, bo nic nie wymusza spójności przy pisaniu.

Co faktycznie daje format strukturalny?

Gwarancję, że każdy wpis ma tę samą formę, sprawdzaną, gdy wpis jest pisany, zamiast zgadywaną, gdy jest czytany. Plik JSON lub YAML z określonym schematem, typ, data, wersja, odbiorca, treść, link, zawodzi głośno, jeśli brakuje wymaganego pola, tak samo jak zrobiłaby to ścisła odpowiedź API; plik Markdown po prostu renderuje to, co tam jest, poprawnie czy nie. Ta różnica jest niewidoczna aż do dnia, gdy skrypt potrzebuje daty każdego wpisu, żeby posortować strumień, a połowa wpisów ma ją w innym miejscu.

# CHANGELOG.yml
- date: 2026-09-05
  type: breaking
  version: v2
  audience: api
  body: "POST /invoices now rejects a currency mismatch instead of silently converting."
  link: /blog/api-changelog/

Czy to znaczy, że plik czytelny dla człowieka musi zniknąć?

Nie, i próba sprawienia, żeby plik YAML lub JSON pełnił podwójną rolę tego, co człowiek czyta w pull requeście, to zwykle błąd w drugą stronę: przeglądanie diffa zagnieżdżonego JSON-a jest gorsze niż przeglądanie zdania prozy, a recenzentka, która musi mentalnie sparsować strukturę danych, żeby wyłapać błąd sformułowania, to recenzentka, która w końcu przestanie wyłapywać błędy sformułowań. Oba formaty mogą współistnieć: dane strukturalne są źródłem prawdy, które czyta pipeline automatyzacji, a wygenerowane renderowanie w Markdown lub HTML jest tym, co człowiek faktycznie recenzuje i czyta, wyprodukowane z pliku strukturalnego zamiast utrzymywane ręcznie obok.

Który format strukturalny jest faktycznie łatwiejszy do ręcznej edycji, JSON czy YAML?

YAML, dla każdego, kto pisze wpisy ręcznie zamiast przez generator, bo eliminuje cudzysłowowanie i dopasowywanie nawiasów, których JSON wymaga dla każdego stringa i zagnieżdżonego obiektu. Kompromis jest taki, że wrażliwość YAML-a na białe znaki zawodzi cicho w sposób, w jaki niedopasowania nawiasów w JSON-ie zwykle nie zawodzą: parser JSON od razu odrzuca źle sformowane dane wejściowe, podczas gdy parser YAML może zaakceptować źle wcięty plik i po prostu sparsować go do złej struktury, co jest gorszą awarią, bo nic wam nie mówi, że to się stało. Jeśli wpisy zawsze pisze tylko skrypt, ten kompromis w dużej mierze znika, a bardziej rygorystyczne parsowanie JSON-a staje się bezpieczniejszym wyborem domyślnym.

Czy strona changeloga potrzebuje własnego formatu strukturalnego, oddzielnego od pliku, który ją zasila?

Nie oddzielnego, tego samego, tylko inaczej wyrenderowanego. Strona changeloga ujmuje, jak sprawić, by sama strona była czytelna maszynowo przez strumień JSON i znaczniki schema.org; ten strumień to wygenerowany output, nie drugie źródło prawdy do utrzymywania w synchronizacji z leżącym u podstaw plikiem. Ręczne utrzymywanie danych strukturalnych w dwóch miejscach, pliku źródłowym i strumieniu strony, to sposób, w jaki te dwa się rozjeżdżają, więc decyzja o formacie pliku podjęta tutaj powinna być tą jedyną rzeczą, z której generowane jest wszystko poniżej, strona, widżet, mail, nigdy ręcznie kopiowane.

Czy koszt migracji istniejącego changeloga w Markdown do formatu strukturalnego się opłaca?

Zwykle dopiero gdy automatyzacja jest prawdziwym celem, nie wcześniej. Jednoosobowy projekt publikujący plik Markdown w README na GitHubie nie ma prawdziwej potrzeby automatyzacji, a konwersja do YAML-a nie kupuje niczego poza ceremonią. Konwersja zwraca się w momencie, gdy więcej niż jeden konsument w dole strumienia, strona, mail podsumowujący, publiczny strumień, musi czytać te same dane, bo to dokładnie ten moment, w którym niespójności parsera Markdown zaczynają produkować widocznie błędny output zamiast być tylko uciążliwe w utrzymaniu.

FAQ

Czy changelog w Markdown może stać się parsowalny bez całkowitej zmiany formatu? Częściowo, z frontmatterem: małym blokiem YAML na górze każdego wpisu (data, typ, wersja) obok treści Markdown dla prozy. To daje strukturalne pola, których potrzebuje parser, bez zmuszania całego wpisu do JSON-a czy YAML-a, i jest rozsądnym środkiem dla zespołu jeszcze nieprzygotowanego do pełnej migracji.

Czy format pliku ma znaczenie dla SEO albo dla tego, jak rankuje strona changeloga? Nie bezpośrednio. Wyszukiwarki czytają wyrenderowaną stronę, nie plik źródłowy, więc format pliku jest dla nich niewidoczny; to, co liczy się dla samej strony, to czy jest czytelna maszynowo z własnego prawa, co jest osobną sprawą od tego, co ją generuje.

Czy każdy wpis changeloga powinien przechodzić przez ten sam plik, czy typy mogą być podzielone na wiele plików? Jeden plik jest prostszy, dopóki wolumen wpisów nie sprawi, że diffowanie czy recenzowanie stanie się niewygodne; podział według roku lub kategorii to rozsądny zawór bezpieczeństwa, gdy diffy jednego pliku staną się za duże, żeby sensownie je recenzować, ale dodaje krok scalania, zanim cokolwiek w dole strumienia może przeczytać “wszystkie wpisy” jako jedną listę.

Czy istnieje standardowy format pliku changeloga, tak jak istnieje standard dla RSS? Nie ma szeroko przyjętego. Keep a Changelog proponuje konwencję Markdown, a kilka narzędzi ma własne; changeset to plik Markdown z frontmatterem YAML wskazującym pakiet i rodzaj podbicia wersji, czyli wzorzec z frontmatterem opisany wyżej. Żaden z nich nie jest formatem, który inne narzędzia czytają od razu tak, jak czytniki RSS powszechnie rozumieją RSS.

Twierdzenia techniczne w tym artykule nie zostały niezależnie zweryfikowane. Jeśli coś się nie zgadza, daj nam znać, a poprawimy to.

Powiązane w changeloop: Porównanie narzędzi do changeloga, Generator changeloga