mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-29 16:54:12 +02:00
Merge pull request #231 from m-aciek/master
Add pl v1.0.0 translation, rename pl-PL to pl
This commit is contained in:
Olivier Lacan
GitHub
commit
3fdadd9b61
@ -1,7 +1,7 @@
|
||||
---
|
||||
description: Prowadź Changelog
|
||||
title: Prowadź Changelog
|
||||
language: pl-PL
|
||||
language: pl
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
302
source/pl/1.0.0/index.html.haml
Normal file
302
source/pl/1.0.0/index.html.haml
Normal file
@ -0,0 +1,302 @@
|
||||
---
|
||||
description: Prowadź Changelog
|
||||
title: Prowadź Changelog
|
||||
language: pl
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
|
||||
- gemnasium = "https://gemnasium.com/"
|
||||
- gh = "https://github.com/olivierlacan/keep-a-changelog"
|
||||
- issues = "https://github.com/olivierlacan/keep-a-changelog/issues"
|
||||
- semver = "http://semver.org/"
|
||||
- shields = "http://shields.io/"
|
||||
- thechangelog = "http://5by5.tv/changelog/127"
|
||||
- vandamme = "https://github.com/tech-angels/vandamme/"
|
||||
- iso = "http://www.iso.org/iso/home/standards/iso8601.htm"
|
||||
- ghr = "https://help.github.com/articles/creating-releases/"
|
||||
|
||||
.header
|
||||
.title
|
||||
%h1 Prowadź Changelog
|
||||
%h2 Nie pozwól swoim znajomym wklejać logów Gita do changelogów.
|
||||
|
||||
= link_to changelog do
|
||||
Wersja
|
||||
%strong= current_page.metadata[:page][:version]
|
||||
|
||||
%pre.changelog= 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ą,
|
||||
chronologicznie uporządkowaną 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 jest na pierwszym miejscu.
|
||||
%li
|
||||
Wyszczególniona jest data wydania każdej wersji.
|
||||
%li
|
||||
Wzmianka, czy przestrzegasz #{link_to "wersjonowania semantycznego", semver}.
|
||||
|
||||
%a.anchor{ href: "#types", aria_hidden: "true" }
|
||||
%h4#types Typy zmian
|
||||
|
||||
%ul
|
||||
%li
|
||||
%code Added
|
||||
dla nowych funkcjonalności.
|
||||
%li
|
||||
%code Changed
|
||||
dla zmian w istniejących funkcjonalnościach.
|
||||
%li
|
||||
%code Deprecated
|
||||
dla funkcjonalności wkrótce do usunięcia.
|
||||
%li
|
||||
%code Removed
|
||||
dla teraz usuniętych funkcjonalności.
|
||||
%li
|
||||
%code Fixed
|
||||
dla jakichkolwiek poprawek błędów.
|
||||
%li
|
||||
%code Security
|
||||
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>Unreleased</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>Unreleased</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: 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 deprecjacji
|
||||
|
||||
%p
|
||||
Gdy ludzie robią upgrade z jednej wersji na drugą, powinno być bezboleśnie
|
||||
jasne kiedy coś się złamie. Powinno być możliwe upgrade'owanie się do wersji,
|
||||
która wypisuje deprecjacje, usunięcie tego, co jest zdezaprobowane, następnie
|
||||
upgrade'owanie się do wersji, w której deprecjacje stają się usunięciami.
|
||||
|
||||
%p
|
||||
Jeśli nie robisz nic więcej, wypisz deprecjacje, usunięcia i jakiekolwiek
|
||||
zmiany łamiące zgodność wstecz w swoim changelogu.
|
||||
|
||||
%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 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", iso}, wynika rekomendacja
|
||||
tego formatu daty do wpisów w changelogu.
|
||||
|
||||
%aside
|
||||
Jest tego więcej. Pomóż mi zebrać te antywzorce
|
||||
= link_to "otwierając zgłoszenie", issues
|
||||
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.", changelog
|
||||
Pochodzi z obserwowania dobrych praktyk w społeczności open source i zebrania ich.
|
||||
|
||||
%p
|
||||
Zdrowa krytyka, dyskusja i sugestie poprawek
|
||||
= link_to "są mile widziane.", issues
|
||||
|
||||
|
||||
%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 końcowym użytkownikom w sposób konsewenty
|
||||
odnajdować istotne zmiany?
|
||||
|
||||
%h4#github-releases
|
||||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||||
Co z GitHub Releases?
|
||||
|
||||
%p
|
||||
To wspaniała inicjatywa. #{link_to "Releases", ghr} 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 taga 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 nie najł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", vandamme} jest gemem Ruby stworzonym przez zespół
|
||||
#{link_to "Gemnasium", 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 [YANKED]</code>
|
||||
|
||||
%p
|
||||
Etykieta <code>[YANKED]</code> jest celowo zapisany 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ę, <strong>#{link_to "zabieraj się za robotę", gh}</strong>.
|
||||
|
||||
.press
|
||||
%h3 Rozmowy
|
||||
%p
|
||||
Byłem na #{link_to "podcaście Changelog", 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