diff --git a/CHANGELOG.md b/CHANGELOG.md index 5bf4db5..859eefb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - v1.1 Italian translation. +- v1.1 Polish translation. ## [1.1.1] - 2023-03-05 diff --git a/source/pl/1.1.0/index.html.haml b/source/pl/1.1.0/index.html.haml new file mode 100644 index 0000000..d156e8f --- /dev/null +++ b/source/pl/1.1.0/index.html.haml @@ -0,0 +1,308 @@ +--- +description: Prowadź Changelog +title: Prowadź Changelog +language: pl +version: 1.0.0 +--- +.header + .title + %h1 Prowadź Changelog + %h2 Nie pozwól swoim znajomym wklejać logów Gita do changelogów. + + = 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ą dla ludzi, 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ę Niewydane 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 Niewydane + 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 2017-07-17 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 CHANGELOG.md. Niektóre projekty używają + HISTORY, NEWS lub RELEASES. + + %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 v1.0.0) + 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 (README, CONTRIBUTING + 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 ## 0.0.5 - 2014-12-13 [WYCOFANA] + + %p + Etykieta [WYCOFANA] 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ą prawdą; 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ę, #{link_to "wtrąć się", data.links.repo}. + +.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.