mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-28 16:24:07 +02:00
Updated Polish translation to v1.1 (#557)
This commit is contained in:
Przemysław Sztoch
GitHub
parent
ea378c61aa
commit
0f00ac59d5
@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||||||
### Added
|
### Added
|
||||||
|
|
||||||
- v1.1 Italian translation.
|
- v1.1 Italian translation.
|
||||||
|
- v1.1 Polish translation.
|
||||||
|
|
||||||
## [1.1.1] - 2023-03-05
|
## [1.1.1] - 2023-03-05
|
||||||
|
|
||||||
|
|||||||
308
source/pl/1.1.0/index.html.haml
Normal file
308
source/pl/1.1.0/index.html.haml
Normal file
@ -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ą <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.
|
||||||
Loading…
x
Reference in New Issue
Block a user