---
title: Prowadź Changelog
description: Nie pozwól swoim znajomym wklejać logów Gita do changelogów.
language: pl
version: 1.0.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&nbsp;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&nbsp;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&nbsp;dokumentacji itp.

  %p
    Zadaniem commita jest udokumentowanie kroku w&nbsp;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&nbsp;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&nbsp;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&nbsp;changelogu.

  %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.