mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-28 08:14:06 +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
|
||||
|
||||
- v1.1 Italian translation.
|
||||
- v1.1 Polish translation.
|
||||
|
||||
## [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