Merge branch 'master' into cs-v1.0.0
This commit is contained in:
Olivier Lacan
GitHub
commit
0e8c9851f3
|
|
@ -26,6 +26,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
|
|||
- Polish translation from @amielucha.
|
||||
- Russian translation from @aishek.
|
||||
- Czech translation from @h4vry.
|
||||
- Slovak translation from @jkostolansky.
|
||||
|
||||
### Changed
|
||||
- Start using "changelog" over "change log" since it's the common usage.
|
||||
|
|
|
|||
|
|
@ -60,6 +60,9 @@ $languages = {
|
|||
русский, но вы можете <a href='/en/'>прочитать её на английском</a> и <a
|
||||
href='#{issues_url}'>помочь с переводом</a>."
|
||||
},
|
||||
"sk" => {
|
||||
name: "Slovenčina"
|
||||
},
|
||||
"sl" => {
|
||||
name: "Slovenščina"
|
||||
},
|
||||
|
|
@ -77,8 +80,8 @@ $languages = {
|
|||
notice: "最新版 (#{$last_version}) 暂时还没有翻译到简体中文，您可以阅读最新的英语版，并且帮助翻译，不胜感激。"
|
||||
},
|
||||
"zh-TW" => {
|
||||
name: "繁體中文",
|
||||
notice: "最新版 (#{$last_version}) 暫時還沒有翻譯到繁體中文，您可以閱讀最新的英語版，並且幫助翻譯，不勝感激。"
|
||||
name: "正體中文",
|
||||
notice: "最新版 (#{$last_version}) 暫時還沒有翻譯到正體中文，您可以閱讀最新的英語版，並且幫助翻譯，不勝感激。"
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -33,7 +33,6 @@ h1
|
|||
margin-bottom: 0
|
||||
line-height: 1
|
||||
text-transform: lowercase
|
||||
width: 50%
|
||||
|
||||
h2
|
||||
font-size: 1.2em
|
||||
|
|
@ -97,3 +96,7 @@ pre, code
|
|||
font-family: $source-code-font-family
|
||||
code
|
||||
white-space: nowrap
|
||||
|
||||
@media (min-width: 1077px)
|
||||
h1
|
||||
width: 50%
|
||||
|
|
|
|||
|
|
@ -2,26 +2,28 @@ $break-small: em(480px)
|
|||
$break-medium: em(800px)
|
||||
$break-large: em(1024px)
|
||||
|
||||
body
|
||||
margin: 0
|
||||
|
||||
article
|
||||
margin: 0 auto
|
||||
width: 65em
|
||||
max-width: 65em
|
||||
|
||||
.main
|
||||
background-color: $color-white
|
||||
margin-bottom: 2em
|
||||
|
||||
div
|
||||
padding-left: 20%
|
||||
padding-right: 20%
|
||||
padding-left: 5%
|
||||
padding-right: 5%
|
||||
padding-bottom: 3em
|
||||
|
||||
aside
|
||||
background-color: lighten(desaturate($color-bark, 5%), 10%)
|
||||
margin-bottom: -3em
|
||||
margin-left: -35%
|
||||
margin-right: -35%
|
||||
margin-left: -5%
|
||||
margin-right: -5%
|
||||
margin-top: 3em
|
||||
padding: 2em 20%
|
||||
padding: 2em 5%
|
||||
text-align: center
|
||||
|
||||
aside &
|
||||
|
|
@ -41,3 +43,19 @@ article ul
|
|||
line-height: 1.5
|
||||
list-style-type: square
|
||||
padding-left: 1em
|
||||
|
||||
@media (min-width: 1077px)
|
||||
body
|
||||
margin: 8px
|
||||
|
||||
.main
|
||||
margin-bottom: 2em
|
||||
|
||||
div
|
||||
padding-left: 20%
|
||||
padding-right: 20%
|
||||
|
||||
aside
|
||||
margin-left: -35%
|
||||
margin-right: -35%
|
||||
padding: 2em 20%
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ div.header
|
|||
padding-bottom: 0.1em
|
||||
background-color: $color-ocre
|
||||
background-image: image-url("bg-hero@2x.png")
|
||||
background-size: 100%
|
||||
background-size: cover
|
||||
|
||||
h1
|
||||
color: $color-sand
|
||||
|
|
@ -33,8 +33,8 @@ div.header
|
|||
|
||||
div.answers
|
||||
margin-top: 12em
|
||||
padding-left: 25%
|
||||
padding-right: 25%
|
||||
padding-left: 5%
|
||||
padding-right: 5%
|
||||
background-color: $color-white
|
||||
|
||||
h3
|
||||
|
|
@ -61,14 +61,9 @@ div.answers
|
|||
h3
|
||||
font-size: 1.6em
|
||||
font-weight: bold
|
||||
width: 50%
|
||||
|
||||
h4
|
||||
padding-left: 15em
|
||||
|
||||
ul
|
||||
font-size: 1em
|
||||
padding-left: 16em
|
||||
|
||||
p
|
||||
a
|
||||
|
|
@ -102,18 +97,16 @@ div.bad-practices
|
|||
font-size: 1.7em
|
||||
color: $color-gold
|
||||
float: left
|
||||
width: 35%
|
||||
|
||||
h4, p
|
||||
padding-left: 12em
|
||||
|
||||
p
|
||||
clear: left
|
||||
font-size: 1em
|
||||
|
||||
div.effort
|
||||
padding-top: 2em
|
||||
padding-left: 25%
|
||||
padding-right: 25%
|
||||
padding-left: 5%
|
||||
padding-right: 5%
|
||||
background-color: $color-white
|
||||
|
||||
h3
|
||||
|
|
@ -123,8 +116,8 @@ div.effort
|
|||
|
||||
div.frequently-asked-questions
|
||||
padding-top: 2em
|
||||
padding-left: 25%
|
||||
padding-right: 25%
|
||||
padding-left: 5%
|
||||
padding-right: 5%
|
||||
background-color: $color-white
|
||||
|
||||
h2
|
||||
|
|
@ -178,3 +171,31 @@ div.frequently-asked-questions
|
|||
content: ""
|
||||
display: table
|
||||
clear: both
|
||||
|
||||
@media (min-width: 1077px)
|
||||
div.answers
|
||||
padding-left: 25%
|
||||
padding-right: 25%
|
||||
|
||||
div.effort
|
||||
padding-left: 25%
|
||||
padding-right: 25%
|
||||
|
||||
div.frequently-asked-questions
|
||||
padding-left: 25%
|
||||
padding-right: 25%
|
||||
|
||||
.good-practices
|
||||
h3
|
||||
width: 50%
|
||||
h4
|
||||
padding-left: 15em
|
||||
ul
|
||||
padding-left: 16em
|
||||
|
||||
.bad-practices
|
||||
h3
|
||||
width: 35%
|
||||
|
||||
h4, p
|
||||
padding-left: 12em
|
||||
|
|
|
|||
|
|
@ -0,0 +1,303 @@
|
|||
---
|
||||
description: Udržuj changelog
|
||||
title: Udržuj changelog
|
||||
language: sk
|
||||
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 Udržuj changelog
|
||||
%h2 Nenechaj kamarátov sypať git logy do changelogov.
|
||||
|
||||
= link_to changelog do
|
||||
Verzia
|
||||
%strong= current_page.metadata[:page][:version]
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
|
||||
.answers
|
||||
%h3#what
|
||||
%a.anchor{ href: "#what", aria_hidden: "true" }
|
||||
Čo je to changelog?
|
||||
|
||||
%p
|
||||
Changelog je súbor obsahujúci organizovaný, chronologicky usporiadaný
|
||||
zoznam významných zmien pre každú verziu daného projektu.
|
||||
|
||||
%h3#why
|
||||
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||||
Prečo udržiavať changelog?
|
||||
|
||||
%p
|
||||
Aby používatelia a prispievatelia presne vedeli, aké podstatné zmeny
|
||||
sa udiali medzi jednotlivými vydaniami (alebo verziami) projektu.
|
||||
|
||||
%h3#who
|
||||
%a.anchor{ href: "#who", aria_hidden: "true" }
|
||||
Kto potrebuje changelog?
|
||||
|
||||
%p
|
||||
Ľudia. Či už konzumenti, alebo vývojári, koncoví používatelia softvéru
|
||||
sú ľudské bytosti, ktorým záleží na tom, čo softvér obsahuje. Keď sa
|
||||
softvér zmení, ľudia chcú vedieť prečo a ako.
|
||||
|
||||
.good-practices
|
||||
%h3#how
|
||||
%a.anchor{ href: "#how", aria_hidden: "true" }
|
||||
Ako vytvorím dobrý changelog?
|
||||
|
||||
%h4#principles
|
||||
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
||||
Hlavné princípy
|
||||
|
||||
%ul
|
||||
%li
|
||||
Changelogy sú <em>pre ľudí</em>, nie stroje.
|
||||
%li
|
||||
Changelog by mal obsahovať záznam pre každú jednu verziu.
|
||||
%li
|
||||
Rovnaké typy zmien by mali byť zoskupené.
|
||||
%li
|
||||
Mala by existovať možnosť odkazovať na jednotlivé verzie a sekcie.
|
||||
%li
|
||||
Posledná verzia je uvedená na prvom mieste.
|
||||
%li
|
||||
Pre každú verziu je uvedený dátum jej vydania.
|
||||
%li
|
||||
Uveď tiež, že sa držíš #{link_to "sémantického verziovania", semver}.
|
||||
|
||||
%a.anchor{ href: "#types", aria_hidden: "true" }
|
||||
%h4#types Typy zmien
|
||||
|
||||
%ul
|
||||
%li
|
||||
%code Added
|
||||
pre nové funkcie.
|
||||
%li
|
||||
%code Changed
|
||||
pre zmeny existujúcej funkcie.
|
||||
%li
|
||||
%code Deprecated
|
||||
pre funkcie, ktoré budú čoskoro odstránené.
|
||||
%li
|
||||
%code Removed
|
||||
pre odstránené funkcie.
|
||||
%li
|
||||
%code Fixed
|
||||
pre opravy chýb.
|
||||
%li
|
||||
%code Security
|
||||
v prípade bezpečnostných zraniteľností.
|
||||
|
||||
.effort
|
||||
|
||||
%h3#effort
|
||||
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
||||
Ako minimalizovať úsilie vynaložené na udržiavanie changelogu?
|
||||
|
||||
%p
|
||||
Udržuj <code>Unreleased</code> sekciu na začiatku changelogu
|
||||
pre nadchádzajúce zmeny.
|
||||
|
||||
%p Má to dva dôvody:
|
||||
|
||||
%ul
|
||||
%li
|
||||
Ľudia môžu vidieť, aké zmeny môžu očakávať v ďalších vydaniach
|
||||
%li
|
||||
V čase vydávania novej verzie môžeš presunúť zmeny z
|
||||
<code>Unreleased</code> sekcie do sekcie novej verzie
|
||||
|
||||
.bad-practices
|
||||
%h3#bad-practices
|
||||
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||||
Môžu byť changelogy zlé?
|
||||
|
||||
%p Áno. Tu je hneď niekoľko spôsobov, ako môžu byť neužitočné.
|
||||
|
||||
%h4#log-diffs
|
||||
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||||
Diffy z commit logu
|
||||
|
||||
%p
|
||||
Použitie diffov z commit logu ako changelog nie je dobrý nápad:
|
||||
sú plné balastu. Veci ako merge commity, commity s nejasnými názvami,
|
||||
zmeny dokumentácie a pod.
|
||||
|
||||
%p
|
||||
Účel commitu je dokumentovanie kroku v evolúcii zdrojového kódu.
|
||||
Niektoré projekty commity prečisťujú, iné nie.
|
||||
|
||||
%p
|
||||
Účelom changelogu je dokumentovanie významných zmien, často naprieč
|
||||
viacerými commitmi, a jasne ich komunikovať koncovému používateľovi.
|
||||
|
||||
%h4#ignoring-deprecations
|
||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||
Ignorovanie oznámenia zastaralých funkcií
|
||||
|
||||
%p
|
||||
Keď používatelia prechádzajú na novšiu verziu, musí byť jasné, čo sa
|
||||
rozbije. Mala by pre nich existovať možnosť prejsť na verziu so zoznamom
|
||||
zastaralých funkcií, tieto funkcie odstrániť a následne prejsť na verziu,
|
||||
kde sú tieto zastaralé funkcie už odstránené.
|
||||
|
||||
%p
|
||||
Ak už nič iné, tak aspoň uveď zastaralé, odstránené funkcie a všetky zmeny,
|
||||
ktoré môžu niečo rozbiť, do changelogu.
|
||||
|
||||
|
||||
%h4#confusing-dates
|
||||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||
Mätúce dátumy
|
||||
|
||||
%p
|
||||
Regionálne formáty dátumov sa líšia naprieč svetom a často je zložité
|
||||
nájsť formát dátumu, ktorý by bol prívetivý a intuitívny pre všetkých
|
||||
používateľov. Výhodou dátumu vo formáte <code>2017-07-17</code> je poradie
|
||||
od najväčšej jednotky po najmenšiu: rok, mesiac, deň. Tento formát sa tiež
|
||||
neprekrýva s inými formátmi, ktoré zamieňajú pozíciu dňa a mesiaca. Kvôli
|
||||
týmto dôvodom spolu s faktom, že ide o #{link_to "ISO štandard", iso},
|
||||
je tento formát odporučený pre záznamy v changelogu.
|
||||
|
||||
%aside
|
||||
Je toho však viac. Pomôž mi zozbierať tieto antivzory
|
||||
= link_to "otvorením issue", issues
|
||||
alebo pull requestom.
|
||||
|
||||
.frequently-asked-questions
|
||||
%h3#frequently-asked-questions
|
||||
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
||||
Často kladené otázky
|
||||
|
||||
%h4#standard
|
||||
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
||||
Existuje štandardný formát pre changelog?
|
||||
|
||||
%p
|
||||
Nie. Existuje GNU príručka pre štýl changelogu alebo dvojodstavcová
|
||||
GNU "smernica" pre NEWS súbor. Obe sú však nevhodné či nedostatočné.
|
||||
|
||||
%p
|
||||
Tento projekt sa snaží byť
|
||||
= link_to "lepšou konvenciou pre changelog.", changelog
|
||||
Vychádza z pozorovania a zozbierania osvedčených postupov komunity okolo projektov s otvoreným zdrojovým kódom.
|
||||
|
||||
%p
|
||||
Zdravá kritika, diskusia a návrhy na zlepšenie
|
||||
= link_to "sú vítané.", issues
|
||||
|
||||
|
||||
%h4#filename
|
||||
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
||||
Ako by mal byť súbor changelogu pomenovaný?
|
||||
|
||||
%p
|
||||
Nazvi ho <code>CHANGELOG.md</code>. Niektoré projekty používajú tiež
|
||||
<code>HISTORY</code>, <code>NEWS</code> alebo <code>RELEASES</code>.
|
||||
|
||||
%p
|
||||
Je jednoduché myslieť si, že názov changelogu nie je taký dôležitý.
|
||||
Prečo však sťažovať koncovému používateľovi hľadanie významných zmien?
|
||||
|
||||
%h4#github-releases
|
||||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||||
A čo GitHub Releases?
|
||||
|
||||
%p
|
||||
Je to skvelá iniciatíva. Služba #{link_to "Releases", ghr} môže byť použitá
|
||||
pre premenu git tagov (napríklad tagu <code>v1.0.0</code>) na bohaté
|
||||
poznámky k vydaniam manuálnym pridávaním týchto poznámok alebo získaním
|
||||
správ z anotovaných git tagov a vytvorením poznámok k vydaniu z nich.
|
||||
|
||||
%p
|
||||
GitHub Releases vytvorí neprenosný changelog, ktorý môže byť zobrazený
|
||||
používateľom v rámci GitHubu. Je možné ich upraviť na veľmi podobný štýl,
|
||||
aký navrhuje projekt Udržuj changelog, tento postup však býva trochu
|
||||
zložitejší.
|
||||
|
||||
%p
|
||||
Súčasná verzia GitHub Releases tiež nie je ľahko objaviteľná koncovým
|
||||
používateľom, na rozdiel od klasického súboru s názvom napísaným veľkými
|
||||
písmenami (<code>README</code>, <code>CONTRIBUTING</code> atď.). Ďalším
|
||||
menším problémom je, že v súčasnosti nepodporuje odkazy na commit logy
|
||||
medzi jednotlivými vydaniami.
|
||||
|
||||
%h4#automatic
|
||||
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
||||
Môžu byť changelogy automaticky parsované?
|
||||
|
||||
%p
|
||||
Je to zložité, pretože ľudia používajú rôzne formáty a názvy súborov.
|
||||
|
||||
%p
|
||||
#{link_to "Vandamme", vandamme} je Ruby gem vytvorený tímom
|
||||
#{link_to "Gemnasium", gemnasium}, ktorý parsuje mnohé (ale nie všetky)
|
||||
changelogy projektov s otvoreným zdrojovým kódom.
|
||||
|
||||
|
||||
%h4#yanked
|
||||
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
||||
A čo spätne stiahnuté vydania?
|
||||
|
||||
%p
|
||||
Stiahnuté vydania sú verzie, ktoré museli byť neskôr spätne odobraté
|
||||
kvôli vážnej chybe alebo bezpečnostným rizikám. Tieto verzie sa často
|
||||
v changelogu ani neobjavia. Ale mali by sa. Zobrazovať by sa mali takto:
|
||||
|
||||
%p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
|
||||
|
||||
%p
|
||||
Tag <code>[YANKED]</code> kričí naschvál. Je dôležité, aby si ho ľudia
|
||||
všimli. Keďže je uzavretý zátvorkami, je tiež jednoduchšie ho programovo
|
||||
parsovať.
|
||||
|
||||
|
||||
%h4#rewrite
|
||||
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
||||
Mal by sa changelog niekedy prepisovať?
|
||||
|
||||
%p
|
||||
Samozrejme. Vždy sa nájde dobrý dôvod na vylepšenie changelogu. Sám často
|
||||
otváram pull requesty pre pridanie chýbajúceho vydania projektov
|
||||
s otvoreným kódom a neudržiavaným changelogom.
|
||||
|
||||
%p
|
||||
Tiež môže nastať situácia, že v poznámkach k vydaniu určitej verzie sa
|
||||
zabudla spomenúť podstatná zmena. V takom prípade je samozrejme dôležité
|
||||
tento changelog aktualizovať.
|
||||
|
||||
|
||||
%h4#contribute
|
||||
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
||||
Ako môžem prispieť?
|
||||
|
||||
%p
|
||||
Tento dokument nie je úplná <strong>pravda</strong>; je mojím starostlivo
|
||||
zváženým názorom spolu s informáciami a príkladmi, ktoré som zozbieral.
|
||||
|
||||
%p
|
||||
Je tomu tak preto, aby komunita dosiahla určitý konsenzus. Verím, že
|
||||
diskusia je rovnako dôležitá ako samotný výsledok.
|
||||
|
||||
%p
|
||||
Takže, prosím, <strong>#{link_to "prilož ruku k dielu", gh}</strong>.
|
||||
|
||||
.press
|
||||
%h3 Rozhovory
|
||||
%p
|
||||
Zúčastnil som sa podcastu #{link_to "The Changelog", thechangelog},
|
||||
kde sme sa rozprávali o tom, prečo by sa správci projektov a prispievatelia
|
||||
mali zaujímať o changelogy a tiež o motivácii za týmto projektom.
|
||||
Loading…
Reference in New Issue