Jeden wpis changelogu powinien opisywać jedną potwierdzoną zmianę: numer wydania, datę wejścia, zakres użytkowników, działanie przed i po zmianie oraz wymagany krok. Poniższy szablon dotyczy funkcji już wdrożonej, a nie zapowiedzi pierwszej premiery.
Zbierz fakty dla jednej zmiany
Przed pisaniem uzyskaj potwierdzenie od właściciela funkcji. Potrzebujesz jej nazwy, identyfikatora wydania, momentu rzeczywistego wdrożenia i zakresu użytkowników. Nie zamieniaj planowanego terminu z harmonogramu w datę wejścia. Jeśli zmiana działa tylko dla części kont, wskaż tę grupę.
Oddziel nazwę funkcji widoczną dla użytkownika od wewnętrznego numeru zgłoszenia. Numer zgłoszenia pomaga zespołowi odtworzyć decyzję; sam zwykle nie wyjaśnia klientowi działania produktu. Wpis ma pozwolić rozpoznać zmianę bez dostępu do wewnętrznych notatek.
Zapisz wersję i datę bez zgadywania
Użyj oznaczenia wydania przyjętego w produkcie. Nie nadawaj nowego numeru tylko na potrzeby tekstu. Jeśli produkt stosuje SemVer, znaczenie części numeru należy odczytywać zgodnie z jego zasadami i zadeklarowanym publicznym API. Inne schematy nie muszą wyrażać tej samej skali zmiany.
Datę wejścia zapisz jednoznacznie, na przykład w formacie YYYY-MM-DD. Jeżeli znaczenie ma godzina, dodaj strefę czasową. Data napisania wpisu może być inna. Przy etapowym wdrożeniu podaj początek i aktualny zakres, zamiast sugerować jednoczesny dostęp dla wszystkich.
Opisz różnicę przed i po
Najbardziej użyteczne są dwa krótkie zdania: „Przed zmianą…” oraz „Po zmianie…”. Nazwij zachowanie, którego użytkownik rzeczywiście doświadczy. Następnie określ, kogo dotyczy zmiana i czy wymaga działania. Jeśli nie wymaga żadnego kroku, napisz to wprost.
Nie opisuj korzyści, których nie potwierdzono. Zmiana sposobu filtrowania nie dowodzi wzrostu sprzedaży ani oszczędności konkretnej liczby godzin. Wystarczy wyjaśnić nową możliwość i jej ograniczenia. Ceny oraz zasady rozliczeń pozostają w odpowiedniej dokumentacji.
Przykład jednego wpisu
Poniższy przykład jest fikcyjny i nie opisuje wydania Semly.
- Funkcja: filtrowanie listy dokumentów.
- Wydanie: 2.4.1, zgodnie z przykładowym schematem produktu.
- Data wejścia: 2026-10-12.
- Przed zmianą: wybranie drugiego filtra usuwało pierwszy.
- Po zmianie: lista uwzględnia oba wybrane filtry jednocześnie.
- Zakres: użytkownicy wersji 2.4.1 korzystający z listy dokumentów.
- Działanie użytkownika: odświeżyć otwartą listę po aktualizacji.
- Ograniczenie: zmiana nie dotyczy zapisanych szablonów filtrów.
Dzięki wskazaniu ograniczenia czytelnik nie musi zgadywać, czy zmieniło się również działanie szablonów. W realnym wpisie dodaj sprawdzony link do dokumentacji tej funkcji. Jeśli dokumentacji jeszcze nie ma, opisz potrzebny krok bez tworzenia nieistniejącego adresu.
Sprawdź wpis przed zapisaniem
Porównaj każde pole z potwierdzeniem zespołu produktu. Sprawdź wersję, datę, zakres i opis zachowania. Upewnij się, że wymagany krok można wykonać oraz że link prowadzi do aktualnej instrukcji.
Przeczytaj wpis bez kontekstu zgłoszenia. Czy da się ustalić, co zmieniło się dla użytkownika i od kiedy? Jeżeli tekst opisuje kilka niezależnych funkcji, rozdziel je na osobne pozycje w jednym wydaniu. Nie twórz kilku artykułów o tej samej zmianie.
Zachowaj spójność tłumaczeń
Tłumaczenia powinny zachować identyfikator wydania, moment wdrożenia, zakres i ograniczenia. Lokalizacja komunikatu nie potwierdza dostępności funkcji na nowym rynku. Jeżeli dostęp różni się między krajami, wymień to jawnie.
Po korekcie błędu we wpisie zachowaj prawdziwą datę wdrożenia i oznacz aktualizację opisu. Nie przedstawiaj samej poprawki redakcyjnej jako kolejnego wdrożenia. Tak powstaje zwięzły zapis jednej zmiany, który można zweryfikować.
Źródło dotyczące numeracji
Zasady SemVer odnoszą się do zadeklarowanego publicznego API. Nie są obowiązkowym schematem dla każdego produktu SaaS.
