mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-08-23 10:48:16 +02:00
bee0534514
Previously they had to be duplicated from the page frontmatter but that's not necessary and also makes it possible to have correct OpenGraph title and descriptions.
309 lines
11 KiB
Plaintext
309 lines
11 KiB
Plaintext
---
|
|
title: Prowadź Changelog
|
|
description: Nie pozwól swoim znajomym wklejać logów Gita do changelogów.
|
|
language: pl
|
|
version: 1.1.0
|
|
---
|
|
.header
|
|
.title
|
|
%h1= current_page.data.title
|
|
%h2= current_page.data.description
|
|
|
|
= link_to data.links.changelog do
|
|
Wersja
|
|
%strong= current_page.metadata[:page][:version]
|
|
|
|
%pre.changelog{ lang: "en" }= File.read("CHANGELOG.md")
|
|
|
|
.answers
|
|
%h3#what
|
|
%a.anchor{ href: "#what", aria_hidden: "true" }
|
|
Czym jest changelog?
|
|
%p
|
|
Changelog, inaczej rejestr zmian, to plik zawierający utrzymywaną,
|
|
uporządkowaną chronologicznie, listę istotnych zmian dla każdej wersji
|
|
projektu.
|
|
|
|
%h3#why
|
|
%a.anchor{ href: "#why", aria_hidden: "true" }
|
|
Po co prowadzić changelog?
|
|
%p
|
|
Aby użytkownikom i deweloperom łatwiej było dokładnie zobaczyć, jakie
|
|
znaczące zmiany zostały wprowadzane w każdym wydaniu (lub wersji) projektu.
|
|
|
|
%h3#who
|
|
%a.anchor{ href: "#who", aria_hidden: "true" }
|
|
Komu potrzebny jest changelog?
|
|
|
|
%p
|
|
Ludziom. Czy to klienci czy deweloperzy, końcowi użytkownicy oprogramowania
|
|
są istotami ludzkimi, którym nie jest obojętne, co jest w oprogramowaniu.
|
|
Kiedy oprogramowanie się zmienia, ludzie chcą wiedzieć dlaczego i jak.
|
|
|
|
.good-practices
|
|
%h3#how
|
|
%a.anchor{ href: "#how", aria_hidden: "true" }
|
|
Jak zrobić dobry changelog?
|
|
|
|
%h4#principles
|
|
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
|
Zasady przewodnie
|
|
|
|
%ul
|
|
%li
|
|
Changelogi są <em>dla ludzi</em>, nie maszyn.
|
|
%li
|
|
Każda wersja powinna mieć swój wpis.
|
|
%li
|
|
Jednakowe typy zmian powinny być zgrupowane.
|
|
%li
|
|
Wersje i sekcje powinny być linkowalne.
|
|
%li
|
|
Najnowsza wersja na pierwszym miejscu.
|
|
%li
|
|
Wyszczególniona data wydania każdej wersji.
|
|
%li
|
|
Wzmianka, czy przestrzegacie #{link_to "wersjonowania semantycznego", data.links.semver}.
|
|
|
|
%a.anchor{ href: "#types", aria_hidden: "true" }
|
|
%h4#types Typy zmian
|
|
|
|
%ul
|
|
%li
|
|
%code Dodane
|
|
dla nowych funkcjonalności.
|
|
%li
|
|
%code Zmienione
|
|
dla zmian w istniejących funkcjonalnościach.
|
|
%li
|
|
%code Zdezaprobowane
|
|
dla funkcjonalności wkrótce do usunięcia.
|
|
%li
|
|
%code Usunięte
|
|
dla teraz usuwanych funkcjonalności.
|
|
%li
|
|
%code Naprawione
|
|
dla jakichkolwiek poprawek błędów.
|
|
%li
|
|
%code Bezpieczeństwo
|
|
w przypadku luk w zabezpieczeniach.
|
|
|
|
.effort
|
|
|
|
%h3#effort
|
|
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
|
Jak mogę zminimalizować wysiłek wkładany w prowadzenie changelogu?
|
|
%p
|
|
Prowadź sekcję <code>Niewydane</code> na szczycie dokumentu, aby śledzić
|
|
nadchodzące zmiany.
|
|
|
|
%p Ta praktyka ma dwa cele:
|
|
|
|
%ul
|
|
%li
|
|
Ludzie widzą, jakich zmian mogą się spodziewać w nadchodzących
|
|
wydaniach.
|
|
%li
|
|
W momencie wydania możesz przenieść zmiany z sekcji <code>Niewydane</code>
|
|
do sekcji nowego wydania.
|
|
|
|
.bad-practices
|
|
%h3#bad-practices
|
|
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
|
Czy changelogi mogą być złe?
|
|
|
|
%p Tak. Oto kilka sposobów, w jakie mogą być mniej niż użyteczne.
|
|
|
|
%h4#log-diffs
|
|
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
|
Zmiany w commit logu
|
|
|
|
%p
|
|
Używanie zmian w commit logach jako changelogów jest złym pomysłem: commit
|
|
logi są pełne szumu: rzeczy takich jak merge commity, commity z niejasnymi
|
|
tytułami, zmiany w dokumentacji itp.
|
|
|
|
%p
|
|
Zadaniem commita jest udokumentowanie kroku w ewolucji kodu źródłowego.
|
|
Niektóre projekty porządkują commity, niektóre nie.
|
|
|
|
%p
|
|
Zadaniem wpisu w changelogu jest udokumentowanie zmian godnych odnotowania,
|
|
często składających się z wielu commitów, aby przedstawić je jasno
|
|
użytkownikom końcowym.
|
|
|
|
%h4#ignoring-deprecations
|
|
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
|
Ignorowanie dezaprobowań
|
|
|
|
%p
|
|
Gdy ludzie robią upgrade z jednej wersji do drugiej, powinno być bezboleśnie
|
|
jasne kiedy coś się może zepsuć. Powinno być możliwe upgrade'owanie się do
|
|
wersji, która wypisuje zdezaprobowania, usunięcie tego, co jest
|
|
zdezaprobowane, następnie upgrade'owanie się do wersji, w której
|
|
dezaprobowane funkcjonalności są usuwane.
|
|
|
|
%p
|
|
Jeśli nie robisz nic innego, wypisz w swoim changelogu zdezaprobowania,
|
|
usunięcia i jakiekolwiek zmiany łamiące zgodność wstecz.
|
|
|
|
%h4#confusing-dates
|
|
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
|
Mylące daty
|
|
|
|
%p
|
|
Regionalne formaty dat różnią się na świecie i często trudno jest znaleźć
|
|
przyjazny człowiekowi format daty, który wydaje się intuicyjny wszystkim.
|
|
Zaletą dat sformatowanych tak jak <code>2017-07-17</code> jest to, że są one
|
|
uporządkowane od największych do najmniejszych jednostek: roku, miesiąca
|
|
i dnia. Ten format również nie nachodzi w niejednoznaczny sposób na inne
|
|
formaty dat, w przeciwieństwie do niektórych regionalnych formatów, które
|
|
zamieniają miejsce numerów miesiąca i dnia. Z tych powodów i faktu, że
|
|
ten format daty jest #{link_to "standardem ISO", data.links.isodate}, wynika rekomendacja
|
|
tego formatu daty do wpisów w changelogu.
|
|
|
|
%h4#inconsistent-changes
|
|
%a.anchor{ href: "#inconsistent-changes", aria_hidden: "true" }
|
|
Niespójne zmiany
|
|
|
|
%p
|
|
Changelog, który wspomina tylko o niektórych zmianach, może być równie
|
|
niebezpieczny jak brak changeloga. Chociaż wiele zmian może nie być istotnych
|
|
— na przykład usunięcie pojedynczej białej spacji może nie wymagać odnotowania
|
|
— to wszelkie ważne zmiany powinny być wymienione w changelogu.
|
|
Poprzez niekonsekwentne stosowanie zmian, Twoi użytkownicy mogą błędnie myśleć,
|
|
że changelog jest jedynym źródłem prawdy. I tak być powinno. Siła wynika tuaj
|
|
z odpowiedzialności — posiadanie dobrego changeloga oznacza posiadanie konsekwentnie
|
|
aktualizowanego changeloga.
|
|
|
|
%aside
|
|
Jest tego więcej. Pomóż mi zebrać te antywzorce
|
|
= link_to "otwierając zgłoszenie", data.links.issue
|
|
lub pull request.
|
|
|
|
.frequently-asked-questions
|
|
%h3#frequently-asked-questions
|
|
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
|
Często zadawane pytania
|
|
|
|
%h4#standard
|
|
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
|
Czy istnieje standardowy format changelogu?
|
|
|
|
%p
|
|
Niezupełnie. Jest przewodnik stylu changelogu GNU, czy dwuparagrafowe
|
|
„wytyczne” GNU NEWS. Oba dokumenty są nieadekwatne lub niewystarczające.
|
|
|
|
%p
|
|
Ten projekt pretenduje do bycia
|
|
= link_to "lepszą konwencją changelogu.", data.links.changelog
|
|
Pochodzi z obserwowania i zebrania dobrych praktyk w społeczności open
|
|
source.
|
|
|
|
%p
|
|
Zdrowa krytyka, dyskusja i sugestie poprawek
|
|
= link_to "są mile widziane.", data.links.issue
|
|
|
|
|
|
%h4#filename
|
|
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
|
Jak powinien się nazywać plik z changelogiem?
|
|
|
|
%p
|
|
Nazwij go <code>CHANGELOG.md</code>. Niektóre projekty używają
|
|
<code>HISTORY</code>, <code>NEWS</code> lub <code>RELEASES</code>.
|
|
|
|
%p
|
|
Łatwo jest uznać, że nazwa pliku z changelogiem nie ma większego znaczenia,
|
|
lecz po co utrudniać swoim użytkownikom końcowym odnajdowanie w sposób
|
|
konsekwentny istotnych zmian?
|
|
|
|
%h4#github-releases
|
|
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
|
Co z GitHub Releases?
|
|
|
|
%p
|
|
To wspaniała inicjatywa. #{link_to "Releases", data.links.github_releases} mogą być używane do
|
|
zmiany prostych tagów Gita (na przykład taga nazwanego <code>v1.0.0</code>)
|
|
w bogate informacje o wydaniach przez ręczne dodanie informacji lub mogą
|
|
wyciągać oznaczone message tagów i przekształcać je w informacje.
|
|
|
|
%p
|
|
GitHub Releases tworzą nieprzenośny changelog, który może być prezentowany
|
|
użytkownikom tylko w kontekście GitHuba. Można go bardzo upodobnić do
|
|
formatu Prowadź changelog, ale będzie to dość skomplikowane.
|
|
|
|
%p
|
|
Bieżąca wersja wydań GitHub jest też prawdopodobnie nienajłatwiejsza do
|
|
odnalezienia dla użytkowników końcowych, w przeciwieństwie do plików
|
|
o nazwach z wielkimi literami (<code>README</code>, <code>CONTRIBUTING</code>
|
|
itp.). Innym mniejszym brakiem jest to, że interfejs obecnie nie posiada
|
|
linków do logów commitów pomiędzy każdymi wydaniami.
|
|
|
|
%h4#automatic
|
|
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
|
Czy changelogi mogą być parsowane automatycznie?
|
|
|
|
%p
|
|
To trudne, ponieważ ludzie stosują bardzo różne formaty i nazwy plików.
|
|
|
|
%p
|
|
#{link_to "Vandamme", data.links.vandamme} jest gemem Ruby stworzonym przez zespół
|
|
Gemnasium i który parsuje wiele (ale nie wszystkie)
|
|
changelogów projektów open source.
|
|
|
|
|
|
%h4#yanked
|
|
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
|
Co z wycofanymi wydaniami?
|
|
|
|
%p
|
|
Wydania typu yanked to wersje, które musiały zostać usunięte z powodu
|
|
poważnego błędu lub problemów z bezpieczeństwem. Często te wersje nie
|
|
pojawiają się w dziennikach zmian. Powinny. Tak powinieneś je wyświetlać:
|
|
|
|
%p <code>## 0.0.5 - 2014-12-13 [WYCOFANA]</code>
|
|
|
|
%p
|
|
Etykieta <code>[WYCOFANA]</code> jest celowo zapisana wielkimi literami.
|
|
Ważne jest, by zwracano na nią uwagę. Jest otoczona nawiasami, więc jest
|
|
również prostsza do sparsowania przez skrypt.
|
|
|
|
|
|
%h4#rewrite
|
|
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
|
Czy powinno się kiedykolwiek przerabiać changelog?
|
|
|
|
%p
|
|
Pewnie. Zawsze istnieją dobre powody, by ulepszyć changelog. Regularnie
|
|
otwieram pull requesty dodające brakujące wydania do open-source'owych
|
|
projektów z nieutrzymywanymi changelogami.
|
|
|
|
%p
|
|
Może się również zdarzyć, że odkryjesz, iż zapomniałeś udokumentować zmianę
|
|
zrywającą zgodność wsteczną w notatkach dla wersji. Oczywiście ważne jest,
|
|
abyś zaktualizował swój changelog w tym przypadku.
|
|
|
|
|
|
%h4#contribute
|
|
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
|
Jak mogę wnieść swój wkład?
|
|
|
|
%p
|
|
Ten dokument nie jest obiektywną <strong>prawdą</strong>; jest moją
|
|
starannie przemyślaną opinią, z informacjami i przykładami, które zebrałem.
|
|
|
|
%p
|
|
To dlatego, że chcę, aby nasza społeczność osiągnęła konsensus. Wierzę, że
|
|
dyskusja jest tak samo istotna jak efekt końcowy.
|
|
|
|
%p
|
|
Więc proszę, <strong>#{link_to "wtrąć się", data.links.repo}</strong>.
|
|
|
|
.press
|
|
%h3 Rozmowy
|
|
%p
|
|
Byłem na #{link_to "podcaście Changelog", data.links.thechangelog}, aby porozmawiać
|
|
dlaczego opiekunowie i kontrybutorzy powinni dbać o changelogi, a także
|
|
o motywacjach stojących za tym projektem.
|