mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-28 08:14:06 +02:00
Merge branch 'master' into patch-1
This commit is contained in:
Danny Guo
GitHub
commit
988449c909
@ -1,8 +1,8 @@
|
||||
# Changelog
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
@ -25,6 +25,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
|
||||
- Brazilian Portugese translation from @aisamu.
|
||||
- Polish translation from @amielucha.
|
||||
- Russian translation from @aishek.
|
||||
- Czech translation from @h4vry.
|
||||
- Slovak translation from @jkostolansky.
|
||||
- Korean translation from @pierceh89.
|
||||
|
||||
### Changed
|
||||
- Start using "changelog" over "change log" since it's the common usage.
|
||||
@ -65,7 +68,7 @@ benefit both "open" and "closed" source projects equally.
|
||||
|
||||
### Changed
|
||||
- Improve argument against commit logs.
|
||||
- Start following [SemVer](http://semver.org) properly.
|
||||
- Start following [SemVer](https://semver.org) properly.
|
||||
|
||||
## [0.0.8] - 2015-02-17
|
||||
### Changed
|
||||
|
||||
@ -40,7 +40,7 @@ Project maintainers who do not follow or enforce the Code of Conduct in good fai
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [https://contributor-covenant.org/version/1/4][version]
|
||||
|
||||
[homepage]: http://contributor-covenant.org
|
||||
[version]: http://contributor-covenant.org/version/1/4/
|
||||
[homepage]: https://contributor-covenant.org
|
||||
[version]: https://contributor-covenant.org/version/1/4/
|
||||
|
||||
@ -30,7 +30,7 @@ GEM
|
||||
fast_blank (1.0.0)
|
||||
fastimage (2.1.0)
|
||||
ffi (1.9.18)
|
||||
haml (5.0.1)
|
||||
haml (5.0.4)
|
||||
temple (>= 0.8.0)
|
||||
tilt
|
||||
hamster (3.0.0)
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
|
||||
Don’t let your friends dump git logs into changelogs™
|
||||
|
||||
This repository generates http://keepachangelog.com/.
|
||||
This repository generates https://keepachangelog.com/.
|
||||
|
||||
## Development
|
||||
### Dependencies
|
||||
@ -39,6 +39,10 @@ few native speakers of the language you're translating to in the Pull Request
|
||||
comments. They'll help review your translation for simple mistakes and give us
|
||||
a better idea of whether your translation is accurate.
|
||||
|
||||
## Contribute
|
||||
|
||||
Please do contribute! Issues and pull requests are welcome.
|
||||
|
||||
Thank you for your help improving software one changelog at a time!
|
||||
|
||||
[CHANGELOG]: ./CHANGELOG.md
|
||||
|
||||
25
config.rb
25
config.rb
@ -39,14 +39,21 @@ $languages = {
|
||||
l'instant et <a href='#{issues_url}'>aider à la traduire</a>.",
|
||||
new: "Une nouvelle version est disponible"
|
||||
},
|
||||
"id-ID" => {
|
||||
name: "Indonesia",
|
||||
new: "Ada versi baru tersedia"
|
||||
},
|
||||
"it-IT" => {
|
||||
name: "Italiano",
|
||||
notice: "L'ultima versione (#{$last_version}) non è ancora disponibile in
|
||||
Italiano, ma la potete <a href='/en/'>leggere in Inglese</a> per ora e
|
||||
potete <a href='#{issues_url}'>contribuire a tradurla</a>."
|
||||
},
|
||||
"pl-PL" => {
|
||||
name: "Polskie"
|
||||
"nl" => {
|
||||
name: "Nederlands"
|
||||
},
|
||||
"pl" => {
|
||||
name: "polski"
|
||||
},
|
||||
"pt-BR" => {
|
||||
name: "Português do Brasil",
|
||||
@ -60,6 +67,9 @@ $languages = {
|
||||
русский, но вы можете <a href='/en/'>прочитать её на английском</a> и <a
|
||||
href='#{issues_url}'>помочь с переводом</a>."
|
||||
},
|
||||
"sk" => {
|
||||
name: "Slovenčina"
|
||||
},
|
||||
"sl" => {
|
||||
name: "Slovenščina"
|
||||
},
|
||||
@ -77,9 +87,12 @@ $languages = {
|
||||
notice: "最新版 (#{$last_version}) 暂时还没有翻译到简体中文，您可以阅读最新的英语版，并且帮助翻译，不胜感激。"
|
||||
},
|
||||
"zh-TW" => {
|
||||
name: "繁體中文",
|
||||
notice: "最新版 (#{$last_version}) 暫時還沒有翻譯到繁體中文，您可以閱讀最新的英語版，並且幫助翻譯，不勝感激。"
|
||||
}
|
||||
name: "正體中文",
|
||||
notice: "最新版 (#{$last_version}) 暫時還沒有翻譯到正體中文，您可以閱讀最新的英語版，並且幫助翻譯，不勝感激。"
|
||||
},
|
||||
"ko" => {
|
||||
name: "한국어"
|
||||
}
|
||||
}
|
||||
|
||||
activate :i18n,
|
||||
@ -88,7 +101,7 @@ activate :i18n,
|
||||
|
||||
set :gauges_id, ''
|
||||
set :publisher_url, 'https://www.facebook.com/olivier.lacan.5'
|
||||
set :site_url, 'http://keepachangelog.com'
|
||||
set :site_url, 'https://keepachangelog.com'
|
||||
|
||||
redirect "index.html", to: "en/#{$last_version}/index.html"
|
||||
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 161 KiB After Width: | Height: | Size: 161 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 4.2 KiB After Width: | Height: | Size: 2.3 KiB |
@ -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
|
||||
|
||||
@ -41,7 +41,7 @@ version: 0.3.0
|
||||
- Dá se v něm jednoduše odkázat na libovolnou sekci (proto raději Markdown než plain text).
|
||||
- Jedna pod-sekce za verzi.
|
||||
- Seznam vydání ve zpětně-chronologickém pořadí (nejnovější navrchu).
|
||||
- Psaní všech dat ve formátu `RRRR-MM-DD`. (Příklad: `2012-06-02` pro `2. červen 2012`.) Je to mezinárodní, [rozumné](http://xkcd.com/1179/) a nezávislé na jazyce.
|
||||
- Psaní všech dat ve formátu `RRRR-MM-DD`. (Příklad: `2012-06-02` pro `2. červen 2012`.) Je to mezinárodní, [rozumné](https://xkcd.com/1179/) a nezávislé na jazyce.
|
||||
- Explicitní uvedení toho, zda projekt dodržuje [Semantické Verzování][semver].
|
||||
- Každá verze by měla:
|
||||
- Uvádět datum vydání ve výše uvedeném formátu.
|
||||
@ -170,7 +170,7 @@ version: 0.3.0
|
||||
[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/
|
||||
[semver]: https://semver.org/
|
||||
[shields]: https://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
|
||||
308
source/cs/1.0.0/index.html.haml
Normal file
308
source/cs/1.0.0/index.html.haml
Normal file
@ -0,0 +1,308 @@
|
||||
---
|
||||
description: Udržuj Changelog
|
||||
title: Udržuj Changelog
|
||||
language: cs
|
||||
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 = "https://semver.org/"
|
||||
- shields = "https://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 Nenech své kamarády sypat git logy do changelogů.
|
||||
|
||||
= link_to changelog do
|
||||
Verze
|
||||
%strong= current_page.metadata[:page][:version]
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
|
||||
.answers
|
||||
%h3#what
|
||||
%a.anchor{ href: "#what", aria_hidden: "true" }
|
||||
Co je to changelog?
|
||||
|
||||
%p
|
||||
Changelog je soubor, který obsahuje organizovaný, chronologicky seřazený
|
||||
seznam podstatných změn pro každou verzi daného projektu.
|
||||
|
||||
%h3#why
|
||||
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||||
Proč udržovat changelog?
|
||||
|
||||
%p
|
||||
Aby uživatelé a přispěvatelé přesně věděli, jaké podstatné změny byly
|
||||
provedeny mezi jednotlivými vydáními (verzemi) daného projektu.
|
||||
|
||||
%h3#who
|
||||
%a.anchor{ href: "#who", aria_hidden: "true" }
|
||||
Kdo potřebuje changelog?
|
||||
|
||||
%p
|
||||
Lidé. Ať už se jedná o spotřebitele nebo vývojáře, koncoví uživatelé
|
||||
softwaru jsou lidská stvoření, kterým záleží na tom, co software obsahuje.
|
||||
Když se daný software změní, lidé chtějí vědět proč a jak.
|
||||
|
||||
.good-practices
|
||||
%h3#how
|
||||
%a.anchor{ href: "#how", aria_hidden: "true" }
|
||||
Jak vytvořit dobrý changelog?
|
||||
|
||||
%h4#principles
|
||||
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
||||
Hlavní zásady
|
||||
|
||||
%ul
|
||||
%li
|
||||
Changelogy jsou <em>pro lidi</em>, ne pro stroje.
|
||||
%li
|
||||
Changelog by měl obsahovat záznam pro každou verzi.
|
||||
%li
|
||||
Stejné typy změn by měly být seskupené.
|
||||
%li
|
||||
Měla by existovat možnost odkazovat na jednotlivé verze a sekce.
|
||||
%li
|
||||
Poslední verze je na prvním místě.
|
||||
%li
|
||||
U každé verze je poznamenáno datum jejího vydání.
|
||||
%li
|
||||
Zmiňte, zda se držíte #{link_to "Sémantického verzování", semver}
|
||||
|
||||
%a.anchor{ href: "#types", aria_hidden: "true" }
|
||||
%h4#types Typy změn
|
||||
|
||||
%ul
|
||||
%li
|
||||
%code Added
|
||||
pro nové funkce.
|
||||
%li
|
||||
%code Changed
|
||||
pro změny v existující funkcionalitě.
|
||||
%li
|
||||
%code Deprecated
|
||||
pro funkce, které budou brzy odstraněny.
|
||||
%li
|
||||
%code Removed
|
||||
pro odstraněné funkce.
|
||||
%li
|
||||
%code Fixed
|
||||
pro opravy chyb.
|
||||
%li
|
||||
%code Security
|
||||
v případě bezpečnostních zranitelností.
|
||||
|
||||
.effort
|
||||
|
||||
%h3#effort
|
||||
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
||||
Jak minimalizovat úsilí potřebné k udržování changelogu?
|
||||
|
||||
%p
|
||||
Udržováním <code>Unreleased</code> sekce na začátku souboru pro zaznamenávání
|
||||
nadcházejících změn.
|
||||
|
||||
%p To plní hned dva účely:
|
||||
|
||||
%ul
|
||||
%li
|
||||
Lidé uvidí, jaké změny mohou očekávat v následujících vydáních
|
||||
%li
|
||||
V čas vydání stačí přesunout změny z <code>Unreleased</code> sekce
|
||||
do sekce nového vydání.
|
||||
|
||||
.bad-practices
|
||||
%h3#bad-practices
|
||||
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||||
Mohou být changelogy špatné?
|
||||
|
||||
%p Ano. Zde je několik případů, kdy mohou být opakem užitečného.
|
||||
|
||||
%h4#log-diffs
|
||||
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||||
Diffy z commit logu
|
||||
|
||||
%p
|
||||
Používání diffů z commit logu jako changelogu je špatný nápad:
|
||||
jsou plné šumu. Obsahují věci jako merge commity, commity s
|
||||
nejasnými nadpisy, změny v dokumentaci, atd.
|
||||
|
||||
%p
|
||||
Účelem commitu je zdokumentovat krok v evoluci zdrojového kódu.
|
||||
Některé projekty commity pročišťují, jiné zas ne.
|
||||
|
||||
%p
|
||||
Účelem záznamu v changelogu je zdokumentovat podstatné změny,
|
||||
často napříč několika commity, a jasně je sdělit koncovým uživatelům.
|
||||
|
||||
%h4#ignoring-deprecations
|
||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||
Ignorování odstraněných funkcí
|
||||
%p
|
||||
Když lidé upgradují z jedné verze na druhou, mělo by jim být bolestně
|
||||
jasné, když se něco rozbije. Mělo by být možné nejprve upgradovat na verzi,
|
||||
která oznámí, jaké funkce budou odstraněny, dané funkce odstranit
|
||||
a poté upgradovat na verzi, kde jsou zmíněné funkce již odstraněny.
|
||||
|
||||
%p
|
||||
Když už nic jiného, je dobré alespoň vypsat odstraněné funkce a
|
||||
změny, které něco rozbíjí, do changelogu.
|
||||
|
||||
|
||||
%h4#confusing-dates
|
||||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||
Matoucí data
|
||||
|
||||
%p
|
||||
Regionální formáty dat se liší napříč světem a je často složité
|
||||
najít formát, který je přátelský a intuitivní pro všechny.
|
||||
Výhodou dat formátovaných jako <code>2017-07-17</code> je pořadí
|
||||
jednotek od největší po nejmenší: rok, měsíc a den. Tento formát
|
||||
se navíc nepřekrývá s jinými, narozdíl od některých regionálních
|
||||
formátů, které prohazují pozici měsíce a dne. Díky těmto důvodům,
|
||||
a také faktu, že je tento formát #{link_to "ISO standard", iso},
|
||||
je doporučeným formátem pro záznamy v changelogu.
|
||||
|
||||
%aside
|
||||
Je toho však víc. Pomozte mi sesbírat tyto antipatterny
|
||||
= link_to "otevřením issue", issues
|
||||
nebo pull requestu.
|
||||
|
||||
.frequently-asked-questions
|
||||
%h3#frequently-asked-questions
|
||||
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
||||
Časko kladené otázky
|
||||
|
||||
%h4#standard
|
||||
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
||||
Existuje pro formát changelogu nějaký standard?
|
||||
|
||||
%p
|
||||
Ne. Je tu GNU stylová příručka pro changelog, nebo ta dvouodstavcová
|
||||
GNU "směrnice" pro NEWS soubor. Ani jedno však není vhodné či dostačující.
|
||||
|
||||
%p
|
||||
Tento projekt má za cíl být
|
||||
= link_to "lepší konvencí pro changelog.", changelog
|
||||
Pochází z pozorování osvědčených postupů v open source komunitě a jejich
|
||||
shromažďování.
|
||||
|
||||
%p
|
||||
Zdravá kritika, diskuse a návrhy na zlepšení
|
||||
= link_to "jsou vítány.", issues
|
||||
|
||||
|
||||
%h4#filename
|
||||
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
||||
Jak by se soubor s changelogem měl jmenovat?
|
||||
|
||||
%p
|
||||
Pojmenujte ho <code>CHANGELOG.md</code>. Některé projekty
|
||||
používají <code>HISTORY</code>, <code>NEWS</code> nebo <code>RELEASES</code>.
|
||||
|
||||
%p
|
||||
Zatímco je snadné si myslet, že na názvu souboru vašeho changelogu
|
||||
až tak nezáleží, proč koncovým uživatelům ztěžovat hledání významných
|
||||
změn?
|
||||
|
||||
%h4#github-releases
|
||||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||||
A co GitHub Releases?
|
||||
|
||||
%p
|
||||
Je to skvělá iniciativa. Služba #{link_to "Releases", ghr} může být
|
||||
použita na proměnu obyčejných git tagů (například tag s názvem
|
||||
<code>v1.0.0</code>) na bohaté poznámky k vydání manuálním přidáním
|
||||
daných poznámek, nebo může pullnout zprávy z anotovaných git tagů
|
||||
a udělat poznámky k vydání z nich.
|
||||
|
||||
%p
|
||||
GitHub Releases však vytvářejí nepřenosný changelog, který může být
|
||||
zobrazen uživatelům jen v kontextu GitHubu. Je možné je udělat
|
||||
velmi podobné formátu projektu Udržuj Changelog, ale to má
|
||||
tendenci být trochu náročnější.
|
||||
|
||||
%p
|
||||
Aktuální verze GitHub Releases také pravděpodobně není příliš
|
||||
objevitelná koncovými uživateli, narozdíl od typických souborů
|
||||
s názvy psanými velkými písmeny (<code>README</code>,
|
||||
<code>CONTRIBUTING</code>, atd.). Další menší problém je, že
|
||||
Releases aktuálně nenabízí možnost odkazovat na commit logy mezi
|
||||
jednotlivými vydáními.
|
||||
|
||||
%h4#automatic
|
||||
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
||||
Mohou changelogy být automaticky parsovány?
|
||||
|
||||
%p
|
||||
Je to složité, protože lidé používají mnoho rozdílných formátů a názvů
|
||||
souborů.
|
||||
|
||||
%p
|
||||
#{link_to "Vandamme", vandamme} je Ruby gem vytvořený týmem
|
||||
#{link_to "Gemnasium", gemnasium}, který parsuje mnoho (ale ne všechny)
|
||||
changelogy open source projektů.
|
||||
|
||||
|
||||
%h4#yanked
|
||||
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
||||
A co zpětně stažená vydání?
|
||||
|
||||
%p
|
||||
Stažená vydání jsou verze, které musely být zpětně odebrány kvůli vážné
|
||||
chybě nebo bezpečnostním rizikům. Tyto verze se často v changelogu ani
|
||||
neobjevují, ale měly by. Zobrazovat by se měly takto:
|
||||
|
||||
%p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
|
||||
|
||||
%p
|
||||
Tag <code>[YANKED]</code> je křiklavý naschvál. Je důležité, aby si ho
|
||||
lidé všimli. Díky tomu, že je v hranatých závorkách, je také jednodušší ho
|
||||
parsovat programem.
|
||||
|
||||
|
||||
%h4#rewrite
|
||||
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
||||
Měl by se changelog někdy přepisovat?
|
||||
|
||||
%p
|
||||
Jistě. Vždy se najde dobrý důvod pro zlepšení changelogu. Sám často otevírám
|
||||
pull requesty pro přidání chybějících vydání v open source projektech s
|
||||
neudržovanými changelogy.
|
||||
|
||||
%p
|
||||
Je také možné, že zjistíte, že v poznámkách k verzi ve vašem projektu není
|
||||
zmíněna změna, která něco rozbila. V tom případě je samozřejmě důležité,
|
||||
aby byl changelog aktualizován.
|
||||
|
||||
|
||||
%h4#contribute
|
||||
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
||||
Jak mohu přispět?
|
||||
|
||||
%p
|
||||
Tento dokument není čistá <strong>pravda</strong>; je to můj pečlivě
|
||||
zvážený názor, společně s informacemi a příklady, které jsem shromáždil.
|
||||
|
||||
%p
|
||||
Je tomu tak proto, že chci aby naše komunita došla ke společné shodě.
|
||||
Věřím, že diskuse je stejně důležitá jako konečný výsledek.
|
||||
|
||||
%p
|
||||
Takže prosím, <strong>#{link_to "přiložte ruku k dílu", gh}</strong>.
|
||||
|
||||
.press
|
||||
%h3 Rozhovory
|
||||
%p
|
||||
Zúčastnil jsem se #{link_to "podcastu The Changelog", thechangelog},
|
||||
abych promluvil o tom, proč by se správci projektů a přispěvatelé měli
|
||||
starat o changelogy a také o motivaci za tímto projektem.
|
||||
@ -41,7 +41,7 @@ version: 0.3.0
|
||||
- Es ist einfach, jeden Bereich zu verlinken (also besser Markdown als einfacher Text).
|
||||
- Ein Unterkapitel pro Version.
|
||||
- Liste die Releases in umgekehrt chronologischer Reihenfolge auf (neuestes zuoberst).
|
||||
- Schreib alle Daten im Format `JJJJ-MM-TT`. (Beispiel: `2012-06-02` für den `2. Juni 2012`.) Es ist international, [vernünftig](http://xkcd.com/1179/), und sprachunabhängig.
|
||||
- Schreib alle Daten im Format `JJJJ-MM-TT`. (Beispiel: `2012-06-02` für den `2. Juni 2012`.) Es ist international, [vernünftig](https://xkcd.com/1179/), und sprachunabhängig.
|
||||
- Erwähne explizit, ob das Projekt nach [Semantic Versioning][semver] geführt wird.
|
||||
- Jede Version sollte:
|
||||
- Das Release-Datum im oben genannten Format auflisten.
|
||||
@ -177,7 +177,7 @@ version: 0.3.0
|
||||
[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/
|
||||
[semver]: https://semver.org/
|
||||
[shields]: https://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
|
||||
@ -9,8 +9,8 @@ version: 1.0.0
|
||||
- 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/"
|
||||
- semver = "https://semver.org/"
|
||||
- shields = "https://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"
|
||||
|
||||
@ -41,7 +41,7 @@ version: 0.3.0
|
||||
- Easy to link to any section (hence Markdown over plain text).
|
||||
- One sub-section per version.
|
||||
- List releases in reverse-chronological order (newest on top).
|
||||
- Write all dates in `YYYY-MM-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) It’s international, [sensible](http://xkcd.com/1179/), and language-independent.
|
||||
- Write all dates in `YYYY-MM-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) It’s international, [sensible](https://xkcd.com/1179/), and language-independent.
|
||||
- Explicitly mention whether the project follows [Semantic Versioning][semver].
|
||||
- Each version should:
|
||||
- List its release date in the above format.
|
||||
@ -176,7 +176,7 @@ version: 0.3.0
|
||||
[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/
|
||||
[semver]: https://semver.org/
|
||||
[shields]: https://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
|
||||
@ -9,12 +9,14 @@ version: 1.0.0
|
||||
- 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/"
|
||||
- semver = "https://semver.org/"
|
||||
- shields = "https://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/"
|
||||
- gnustyle = "https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs"
|
||||
- gnunews = "https://www.gnu.org/prep/standards/html_node/NEWS-File.html#NEWS-File"
|
||||
|
||||
.header
|
||||
.title
|
||||
@ -75,7 +77,7 @@ version: 1.0.0
|
||||
%li
|
||||
The latest version comes first.
|
||||
%li
|
||||
The release date of each versions is displayed.
|
||||
The release date of each version is displayed.
|
||||
%li
|
||||
Mention whether you follow #{link_to "Semantic Versioning", semver}.
|
||||
|
||||
@ -175,7 +177,7 @@ version: 1.0.0
|
||||
overlap in ambiguous ways with other date formats, unlike some
|
||||
regional formats that switch the position of month and day numbers.
|
||||
These reasons, and the fact this date format is an
|
||||
#{link_to "ISO standard", iso} are why it is the recommended date
|
||||
#{link_to "ISO standard", iso}, are why it is the recommended date
|
||||
format for changelog entries.
|
||||
|
||||
%aside
|
||||
@ -193,9 +195,9 @@ version: 1.0.0
|
||||
Is there a standard changelog format?
|
||||
|
||||
%p
|
||||
Not really. There's the GNU changelog style guide, or the two-
|
||||
paragraph-long GNU NEWS file "guideline". Both are inadequate or
|
||||
insufficient.
|
||||
Not really. There's the #{link_to "GNU changelog style guide",
|
||||
gnustyle}, or the #{link_to "two-paragraph-long GNU NEWS file", gnunews}
|
||||
"guideline". Both are inadequate or insufficient.
|
||||
|
||||
%p
|
||||
This project aims to be
|
||||
|
||||
@ -39,7 +39,7 @@ version: 0.3.0
|
||||
- Fácil de conectar a cualquier sección (de ahí a que se use Markdown sobre texto plano).
|
||||
- Una sub-sección por versión.
|
||||
- Lista los releases en un orden inversamente-cronológico (el más reciente en la parte superior).
|
||||
- Escribe todas las fechas en formato `AAAA-MM-DD`. (Ejemplo: `2012-06-02` en vez de `2 JUN 2012`.) Es internacional, [sensible](http://xkcd.com/1179/), e independientemente del lenguaje que usemos.
|
||||
- Escribe todas las fechas en formato `AAAA-MM-DD`. (Ejemplo: `2012-06-02` en vez de `2 JUN 2012`.) Es internacional, [sensible](https://xkcd.com/1179/), e independientemente del lenguaje que usemos.
|
||||
- Se menciona explícitamente si el proyecto sigue la convención del [Versionamiento Semántico][semver].
|
||||
- Cada versión debería:
|
||||
- Indicar su fecha de lanzamiento en el formato anterior.
|
||||
@ -134,7 +134,7 @@ version: 0.3.0
|
||||
[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/
|
||||
[semver]: https://semver.org/
|
||||
[shields]: https://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
|
||||
@ -9,8 +9,8 @@ version: 1.0.0
|
||||
- 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/"
|
||||
- semver = "https://semver.org/"
|
||||
- shields = "https://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"
|
||||
|
||||
@ -49,7 +49,7 @@ version: 0.3.0
|
||||
- Liste les publications dans l’ordre chronologique inverse (les plus récentes
|
||||
en haut).
|
||||
- Toutes les dates sont au format `AAAA-MM-JJ`. (Exemple: `2012-06-02` pour le
|
||||
`2 Juin 2012`.) C’est international, [raisonnable](http://xkcd.com/1179/) et
|
||||
`2 Juin 2012`.) C’est international, [raisonnable](https://xkcd.com/1179/) et
|
||||
indépendant de la langue.
|
||||
- Mentionne explicitement si le projet respecte le
|
||||
[Versionnage Sémantique][semver].
|
||||
@ -203,7 +203,7 @@ version: 0.3.0
|
||||
[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/
|
||||
[semver]: https://semver.org/
|
||||
[shields]: https://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
|
||||
@ -9,8 +9,8 @@ version: 1.0.0
|
||||
- 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/"
|
||||
- semver = "https://semver.org/"
|
||||
- shields = "https://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"
|
||||
|
||||
329
source/id-ID/1.0.0/index.html.haml
Normal file
329
source/id-ID/1.0.0/index.html.haml
Normal file
@ -0,0 +1,329 @@
|
||||
---
|
||||
description: Pencatatan Changelog
|
||||
title: Pencatatan Changelog
|
||||
language: id-ID
|
||||
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 = "https://semver.org/"
|
||||
- shields = "https://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/"
|
||||
- aditya = "https://github.com/adityapurwa/"
|
||||
- edicyber = "https://github.com/cyberid41"
|
||||
|
||||
.header
|
||||
.title
|
||||
%h1 Pencatatan Changelog
|
||||
%h2 Standarisasi pencatatan Changelog untuk kolaborasi yang lebih baik
|
||||
|
||||
= link_to changelog do
|
||||
Versi
|
||||
%strong= current_page.metadata[:page][:version]
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
|
||||
.answers
|
||||
%h3#what
|
||||
%a.anchor{ href: "#what", aria_hidden: "true" }
|
||||
Apa itu changelog?
|
||||
|
||||
%p
|
||||
Changelog adalah sebuah file yang berisi daftar perubahan yang
|
||||
diurutkan secara kronologis untuk setiap versi dari sebuah project.
|
||||
|
||||
%h3#why
|
||||
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||||
Kenapa perlu untuk mencatat changelog?
|
||||
|
||||
%p
|
||||
Supaya pengguna dan kontributor lebih mudah melihat perubahan
|
||||
apa saja yang terjadi di setiap rilis (atau versi) dari sebuah project.
|
||||
|
||||
%h3#who
|
||||
%a.anchor{ href: "#who", aria_hidden: "true" }
|
||||
Siapa yang butuh changelog?
|
||||
|
||||
%p
|
||||
Semua orang membutuhkannya. Baik pengguna ataupun pengembang, setiap
|
||||
orang yang menggunakan perangkat lunak adalah manusia yang peduli dengan
|
||||
apa yang ada di perangkat lunak tersebut. Mereka ingin tahu apa
|
||||
dan kenapa terjadi perubahan.
|
||||
|
||||
.good-practices
|
||||
%h3#how
|
||||
%a.anchor{ href: "#how", aria_hidden: "true" }
|
||||
Bagaimana cara membuat changelog yang baik?
|
||||
|
||||
%h4#principles
|
||||
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
||||
Prinsip-prinsip Dasar
|
||||
|
||||
%ul
|
||||
%li
|
||||
Changelog ditulis untuk <em>manusia</em>, bukan mesin.
|
||||
%li
|
||||
Harus ada catatan untuk setiap versi.
|
||||
%li
|
||||
Setiap tipe perubahan yang sama harus dikelompokkan.
|
||||
%li
|
||||
Versi dan seksi harus ditulis dalam bentuk link.
|
||||
%li
|
||||
Versi yang terakhir harus ditulis di paling atas.
|
||||
%li
|
||||
Tiap catatan harus disertai dengan tanggal.
|
||||
%li
|
||||
Berikan informasi jika kalian menggunakan #{link_to "Semantic Versioning", semver}.
|
||||
|
||||
%a.anchor{ href: "#types", aria_hidden: "true" }
|
||||
%h4#types Jenis-jenis perubahan
|
||||
|
||||
%ul
|
||||
%li
|
||||
%code Added/Ditambahkan
|
||||
untuk fitur yang baru.
|
||||
%li
|
||||
%code Changed/Dirubah
|
||||
untuk perubahan di fitur yang sudah ada.
|
||||
%li
|
||||
%code Deprecated/Akan Dhilangkan
|
||||
untuk fitur yang akan dihapus dalam waktu dekat.
|
||||
%li
|
||||
%code Removed/Dihilangkan
|
||||
untuk fitur yang sudah dihapus.
|
||||
%li
|
||||
%code Fixed/Diperbaiki
|
||||
untuk setiap perbaikan bugs.
|
||||
%li
|
||||
%code Security/Keamanan
|
||||
jika ada celah keamanan.
|
||||
|
||||
.effort
|
||||
|
||||
%h3#effort
|
||||
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
||||
Bagaimana usaha untuk menjaga changelog tetap tercatat dengan benar?
|
||||
|
||||
%p
|
||||
Sisakan bagian <code>Unreleased/Belum Dirilis</code> di bagian paling atas
|
||||
file changelog untuk mencatat perubahan yang akan datang.
|
||||
|
||||
|
||||
%p Hal ini berguna untuk dua hal:
|
||||
|
||||
%ul
|
||||
%li
|
||||
People can see what changes they might expect in upcoming releases
|
||||
Orang-orang bisa melihat perubahan apa saja yang akan datang.
|
||||
%li
|
||||
Saat waktu rilis datang, tinggal pindahkan bagian <code>Unreleased/Belum Dirilis</code>
|
||||
ke catatan rilis versi baru di bawah.
|
||||
|
||||
.bad-practices
|
||||
%h3#bad-practices
|
||||
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||||
Apakah changelog bisa menjadi tidak bermanfaat?
|
||||
|
||||
%p Bisa, berikut beberapa skenario ketika changelog menjadi tidak bermanfaat:
|
||||
|
||||
%h4#log-diffs
|
||||
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||||
Menggunakan Commit log diffs sebagai changelog
|
||||
|
||||
%p
|
||||
Menggunakan commit log diffs (catatan perbedaan setiap commit) bisa
|
||||
membuat changelog susah untuk dibaca. Commit dengan judul yang tidak jelas,
|
||||
dokumentasi perubahan, dan sebagainya, malah akan membuat
|
||||
changelog terlalu berisik dan susah dibaca.
|
||||
|
||||
%p
|
||||
The purpose of a commit is to document a step in the evolution of
|
||||
the source code. Some projects clean up commits, some don't.
|
||||
Tujuan utama dari commit adalah untuk mencatat setiap perubahan dari source
|
||||
code. Beberapa project mengatur commitnya, beberapa tidak.
|
||||
|
||||
%p
|
||||
Tujuan dari changelog adalah untuk mencatat perubahan yang pantas
|
||||
untuk dicatat, bisa jadi beberapa commit dijadikan satu catatan
|
||||
untuk lebih memudahkan pembaca.
|
||||
|
||||
%h4#ignoring-deprecations
|
||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||
Mengabaikan Depcreations (fitur yang akan dihilangkan)
|
||||
|
||||
%p
|
||||
Saat menaikkan versi, harus ditulis dengan jelas apa saja
|
||||
yang kira-kira bisa membuat sistem tidak berjalan. Sebaiknya
|
||||
terdapat versi yang mencatat apa saja yang akan dihilangkan,
|
||||
lalu menghapus fitur yang dihilangkan, dan naikkan lagi ke versi
|
||||
dengan fitur yang sudah dihilangkan.
|
||||
|
||||
%p
|
||||
Jika kalian tidak merubah apapun, tetap catat fitur yang akan
|
||||
dihilangkan, fitur yang sudah dihilangkan, dan perubahan-perubahan
|
||||
lain yang bisa membuat sistem tidak berjalan.
|
||||
|
||||
|
||||
%h4#confusing-dates
|
||||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||
Perbedaan Format Tanggal
|
||||
|
||||
%p
|
||||
Format tanggal regional berbeda-beda sesuai dengan budaya masing-masing,
|
||||
dan seringkali perbedaan ini susah untuk dipahami dan dimengerti.
|
||||
Penggunaan format tanggal <code>2017-07-17</code> lebih mudah untuk dimengerti,
|
||||
karena diurutkan berdasarkan unit terbesar: tahun, bulan, dan tanggal.
|
||||
Format ini juga merupakan #{link_to "ISO standard", iso}, sehingga
|
||||
inilah yang dipakai untuk pencatatan changelog.
|
||||
|
||||
%aside
|
||||
Ada beberapa permasalahan lainnya, bantu kami dengan beberapa antipatterns
|
||||
dengan = link_to "mengirimkan issue", issues atau kirimkan pull request.
|
||||
|
||||
.frequently-asked-questions
|
||||
%h3#frequently-asked-questions
|
||||
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
||||
Pertanyaan yang Sering Ditanyakan
|
||||
|
||||
%h4#standard
|
||||
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
||||
Is there a standard changelog format?
|
||||
Apakah ada standar untuk format changelog?
|
||||
|
||||
%p
|
||||
Tidak, ada format GNU untuk changelog, atau format 2 paragraf GNU NEWS.
|
||||
Keduanya tidak benar-benar cukup, gunakan format yang disetujui tim masing-masing.
|
||||
|
||||
%p
|
||||
Project ini ditujukan untuk
|
||||
= link_to "membuat aturan changelog yang lebih baik", changelog
|
||||
berdasarkan observasi beberapa changelog di komunitas open source
|
||||
dan menyatukan mereka.
|
||||
|
||||
%p
|
||||
Kritik yang membangun, diskusi, dan saran untuk perbaikan
|
||||
= link_to "sangat diterima.", issues
|
||||
|
||||
|
||||
%h4#filename
|
||||
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
||||
What should the changelog file be named?
|
||||
Apa nama file yang cocok untuk file changelog?
|
||||
|
||||
%p
|
||||
Gunakan nama <code>CHANGELOG.md</code>, beberapa project
|
||||
menggunakan <code>HISTORY</code>, <code>NEWS</code> atau <code>RELEASE</code>.
|
||||
|
||||
%p
|
||||
Sebenarnya tidak terlalu susah untuk menamai file changelog, cukup
|
||||
berikan nama yang mudah dikenali oleh orang-orang
|
||||
supaya mudah untuk dibaca.
|
||||
|
||||
%h4#github-releases
|
||||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||||
Apa itu GitHub Releases?
|
||||
|
||||
%p
|
||||
#{link_to "Github Release", ghr} adalah salah satu
|
||||
insiatif dari GitHub untuk membuat changelog berdasarkan git tags,
|
||||
contohnya, tag dengan nama <code>v1.0.0</code>. Isi dari changelog
|
||||
bisa ditulis manual atau menggunakan pesan yang ditulis bersamaan dengan
|
||||
tags.
|
||||
|
||||
%p
|
||||
GitHub Releases membuat changelog yang tidak portable dan hanya bisa
|
||||
bekerja dengan baik di lingkup GitHub. Sangat mungkin untuk
|
||||
membuat GitHub Releases terlihat mirip dengan format pencatatan changelog
|
||||
yang dijelaskan di sini, tapi butuh usaha ekstra.
|
||||
|
||||
%p
|
||||
Versi GitHub releases yang sekarang juga tidak terlalu umum
|
||||
untuk orang-orang, dan hanya bisa dibuka melalui sub menu
|
||||
di GitHub, berbeda dengan file-file seperti
|
||||
(<code>README</code>, <code>CONTRIBUTING</code>, dsb.) yang
|
||||
langsung terlihat saat project pertama kali dibuka. Keterbatasan lainnya
|
||||
adalah tidak adanya link di GitHub releases.
|
||||
|
||||
%h4#automatic
|
||||
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
||||
Apakah Changelog Bisa Diparse Secara Otomatis?
|
||||
|
||||
%p
|
||||
Susah, karena orang-orang menggunakan versi dan format
|
||||
changelog yang berbeda-beda.
|
||||
|
||||
%p
|
||||
#{link_to "Vandamme", vandamme} adalah Ruby Gem yang dibuat oleh tim
|
||||
#{link_to "Gemnasium", gemnasium} yang bisa memparse (but
|
||||
not all) changelog beberapa project open source.
|
||||
|
||||
|
||||
%h4#yanked
|
||||
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
||||
Bagaimana dengan Rilis YANKED (rilis yang dibatalkan)?
|
||||
|
||||
%p
|
||||
Rilis yang dibatalkan adalah rilis yang dibatalkan, bisa jadi
|
||||
karena ada bug yang fatal dan permasalahan keamanan. Versi
|
||||
ini sering tidak dimasukkan ke changelog, padahal seharusnya ditulis
|
||||
sebagaimana berikut.
|
||||
|
||||
%p <code>## 0.0.5 - 2014-12-13 [YANKED/DIBATALKAN]</code>
|
||||
|
||||
%p
|
||||
Tag <code>[YANKED/DIBATALKAN]</code> ditulis dengan jelas supaya
|
||||
orang memperhatikannya, dan dikurung dengan kurung kotak supaya
|
||||
mudah untuk diparse.
|
||||
|
||||
|
||||
%h4#rewrite
|
||||
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
||||
Bolehkan Menulis Ulang Changelog?
|
||||
|
||||
%p
|
||||
Tentu saja, ada banyak alasan bagus untuk menulis ulang changelog,
|
||||
salah satunya untuk rilis-rilis yang lupa untuk dituliskan di
|
||||
beberapa project.
|
||||
|
||||
%p
|
||||
Juga sangat mungkin saat menulis ulang, kalian ingat tentang perubahan
|
||||
yang bisa membuat sistem tidak bekerja yang belum dituliskan. Dalam hal ini,
|
||||
sangat penting untuk merubah changelog supaya datanya lebih akurat.
|
||||
|
||||
|
||||
%h4#contribute
|
||||
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
||||
Bagaimana Saya Bisa Berkontribusi?
|
||||
|
||||
%p
|
||||
Dokumen ini bukan kebenaran absolut, ini hanyalah opini yang dikumpulkan
|
||||
dari beberapa informasi dan contoh yang kami kumpulkan.
|
||||
|
||||
%p
|
||||
Ini karena kami ingin komunitasi terus berdiskusi untuk mencapai konsensus
|
||||
yang terbaik untuk pencatatan changelog.
|
||||
|
||||
%p
|
||||
Jadi silahkan, <strong>#{link_to "kirimkan saran", gh}</strong>.
|
||||
|
||||
%h4#about-translation
|
||||
%a.anchor{ href: "#about-translation", aria_hidden: "true" }
|
||||
Tentang Terjemahan Bahasa Indonesia
|
||||
|
||||
%p
|
||||
Terjemahan Bahasa Indonesia diterjemahkan oleh #{link_to "Aditya Purwa", aditya}
|
||||
dan dikoreksi oleh #{link_to "Edi Santoso", edicyber}, silahkan
|
||||
sampaikan jika ada terjemahan yang lebih baik.
|
||||
|
||||
.press
|
||||
%h3 Conversations
|
||||
%p
|
||||
Kami mengisi acara di #{link_to "The Changelog podcast", thechangelog}
|
||||
untuk berbicara tentang kenapa maintainer dan kontributor harus peduli
|
||||
dengan changelog, dan motivasi dari project ini.
|
||||
@ -42,7 +42,7 @@ version: 0.3.0
|
||||
- Easy to link to any section (hence Markdown over plain text).
|
||||
- One sub-section per version.
|
||||
- List releases in reverse-chronological order (newest on top).
|
||||
- Write all dates in `YYYY-MM-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) It’s international, [sensible](http://xkcd.com/1179/), and language-independent.
|
||||
- Write all dates in `YYYY-MM-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) It’s international, [sensible](https://xkcd.com/1179/), and language-independent.
|
||||
- Explicitly mention whether the project follows [Semantic Versioning][semver].
|
||||
- Each version should:
|
||||
- List its release date in the above format.
|
||||
@ -177,7 +177,7 @@ version: 0.3.0
|
||||
[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/
|
||||
[semver]: https://semver.org/
|
||||
[shields]: https://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
|
||||
@ -39,7 +39,7 @@ language: it-IT
|
||||
- Facile da linkare ad altre sezioni (da cui il Markdown invece che testo normale).
|
||||
- Una sotto-sezione per ogni versione.
|
||||
- Elenca le release in ordine cronologico inverso (quelle più recenti all'inizio).
|
||||
- Scrive tutte le date nel formato `YYYY-MM-DD`. (Esempio: `2012-06-02` sta per `2 Giugno 2012`). È internazionale, [sensato](http://xkcd.com/1179/), e indipendente dalla lingua.
|
||||
- Scrive tutte le date nel formato `YYYY-MM-DD`. (Esempio: `2012-06-02` sta per `2 Giugno 2012`). È internazionale, [sensato](https://xkcd.com/1179/), e indipendente dalla lingua.
|
||||
- Dichiara esplicitamente se il progetto segue il [Semantic Versioning][semver].
|
||||
- Ogni versione dovrebbe:
|
||||
- Elencare la sua data di rilascio nel formato sopra specificato.
|
||||
@ -169,7 +169,7 @@ language: it-IT
|
||||
[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/
|
||||
[semver]: https://semver.org/
|
||||
[shields]: https://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
|
||||
@ -9,8 +9,8 @@ version: 1.0.0
|
||||
- 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/"
|
||||
- semver = "https://semver.org/"
|
||||
- shields = "https://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"
|
||||
@ -50,7 +50,7 @@ version: 1.0.0
|
||||
|
||||
%p
|
||||
Le persone ne hanno bisogno. Che si tratti di consumatori o di sviluppatori, gli utenti finali
|
||||
del software sono persone interessate a ciò che avviene in esso.
|
||||
sono persone interessate a ciò che avviene in esso.
|
||||
Se il software è cambiato, allora le persone vogliono sapere come e perché.
|
||||
|
||||
.good-practices
|
||||
@ -64,11 +64,11 @@ version: 1.0.0
|
||||
|
||||
%ul
|
||||
%li
|
||||
I Changelogs sono <em>per le persone</em>, non per le macchine.
|
||||
I changelog sono <em>per le persone</em>, non per le macchine.
|
||||
%li
|
||||
Dovrebbe essere una voce per ogni singola versione.
|
||||
Dovrebbe esserci una voce per ogni singola versione.
|
||||
%li
|
||||
Gli stessi tipi di modifiche dovrebbero essere raggruppati.
|
||||
Le modifiche dello stesso tipo dovrebbero essere raggruppate.
|
||||
%li
|
||||
Versioni e sezioni dovrebbero essere collegabili.
|
||||
%li
|
||||
@ -93,7 +93,7 @@ version: 1.0.0
|
||||
per le funzionalità che saranno rimosse nelle future release.
|
||||
%li
|
||||
%code Removed
|
||||
per funzionalità deprecate rimosse in questa release.
|
||||
per funzionalità rimosse in questa release.
|
||||
%li
|
||||
%code Fixed
|
||||
per tutti i bug fix.
|
||||
@ -133,7 +133,7 @@ version: 1.0.0
|
||||
|
||||
%p
|
||||
Usare i commit log diffs al posto dei changelog è una brutta idea: contengono solo cose superflue.
|
||||
Come come i merge commits, i commits con titoli oscuri,
|
||||
Cose come i merge commits, i commits con titoli oscuri,
|
||||
le modifiche della documentazione, etc.
|
||||
|
||||
%p
|
||||
@ -146,13 +146,13 @@ version: 1.0.0
|
||||
|
||||
%h4#ignoring-deprecations
|
||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||
Ignorare le Deprecazioni
|
||||
Ignorare le deprecazioni
|
||||
%p
|
||||
Quando le persone aggiornano da una versione ad un'altra,
|
||||
dovrebbe essere dolorosamente chiaro che qualcosa si romperà.
|
||||
Dovrebbe essere possibile eseguire l'aggiornamento a una versione
|
||||
che elenca le deprecazioni, rimuove ciò che è deprecato, quindi
|
||||
aggiorna alla versione in cui le deprecazioni diventano rimozioni.
|
||||
che elenca le deprecazioni, rimuovere ciò che è deprecato, quindi
|
||||
aggiornare alla versione in cui le deprecazioni diventano rimozioni.
|
||||
%p
|
||||
Se non fai nient'altro elenca le deprecazioni, le rimozioni e
|
||||
qualsiasi altro cambiamento nel tuo changelog.
|
||||
@ -210,8 +210,8 @@ version: 1.0.0
|
||||
<code>HISTORY</code>, <code>NEWS</code> o <code>RELEASES</code>.
|
||||
|
||||
%p
|
||||
Mentre è facile pensare che il nome del tuo file changelog
|
||||
non sia poi così importante, perchè non rendere facile la
|
||||
Risulta facile pensare che il nome del tuo file changelog
|
||||
non sia poi così importante, allora perchè non rendere facile la
|
||||
vita ai tuoi utenti, usando sempre lo stesso nome?
|
||||
|
||||
%h4#github-releases
|
||||
@ -305,6 +305,6 @@ version: 1.0.0
|
||||
.press
|
||||
%h3 Dialogo
|
||||
%p
|
||||
Sono andato su #{link_to "The Changelog podcast", thechangelog}
|
||||
Sono andato a #{link_to "The Changelog podcast", thechangelog}
|
||||
per parlare del perché i gestori e i contributori dovrebbero preoccuparsi dei changelog
|
||||
e anche delle motivazioni dietro questo progetto.
|
||||
|
||||
287
source/ko/1.0.0/index.html.haml
Normal file
287
source/ko/1.0.0/index.html.haml
Normal file
@ -0,0 +1,287 @@
|
||||
---
|
||||
description: Keep a Changelog
|
||||
title: Keep a Changelog
|
||||
language: ko
|
||||
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 = "https://semver.org/"
|
||||
- shields = "https://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 Changelog 관리
|
||||
%h2 동료가 git 로그를 changelogs에 덤프하게 내버려 두지 마세요.
|
||||
|
||||
= link_to changelog do
|
||||
Version
|
||||
%strong= current_page.metadata[:page][:version]
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
|
||||
.answers
|
||||
%h3#what
|
||||
%a.anchor{ href: "#what", aria_hidden: "true" }
|
||||
Changelog는 무엇인가요?
|
||||
|
||||
%p
|
||||
Changelog는 프로젝트의 각 버전에 대해 선별된 눈에 띄는 변경사항을 시간 순서대로 정리해둔 파일입니다.
|
||||
|
||||
%h3#why
|
||||
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||||
왜 changelog를 유지해야 하나요?
|
||||
|
||||
%p
|
||||
사용자와 기여자가 프로젝트의 각 릴리즈(또는 버전)간에 정확히 어떤 주목할만한 변경사항이 있는지 보기 쉽도록 합니다.
|
||||
|
||||
%h3#who
|
||||
%a.anchor{ href: "#who", aria_hidden: "true" }
|
||||
누가 changelog를 필요로 하나요?
|
||||
|
||||
%p
|
||||
사람들이 필요로 합니다. 개발자이든 사용자이든, 소프트웨어의 최종 사용자는 소프트웨어에 무엇이 있는지 관심이 있는 사람입니다.
|
||||
소프트웨어가 변할 때, 사람들은 왜 그리고 어떻게 바뀌었는지 알고 싶어합니다.
|
||||
|
||||
.good-practices
|
||||
%h3#how
|
||||
%a.anchor{ href: "#how", aria_hidden: "true" }
|
||||
어떻게 좋은 changelog를 만들수 있나요?
|
||||
|
||||
%h4#principles
|
||||
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
||||
가이드 원칙
|
||||
|
||||
%ul
|
||||
%li
|
||||
Changelogs는 <em>사람을 위한 것입니다.</em> 기계를 위한 것이 아닙니다.
|
||||
%li
|
||||
모든 단일 버전에 대한 항목이 있어야 합니다.
|
||||
%li
|
||||
같은 유형의 변경사항은 모아야 합니다.
|
||||
%li
|
||||
버전과 섹션은 연결할 수 있어야 합니다.
|
||||
%li
|
||||
최신 버전이 처음에 나옵니다.
|
||||
%li
|
||||
각 버전의 릴리즈 날짜를 표시해야 합니다.
|
||||
%li
|
||||
#{link_to "시멘틱 버저닝", semver}를 따르는지 언급해 주세요.
|
||||
|
||||
%a.anchor{ href: "#types", aria_hidden: "true" }
|
||||
%h4#types 변경 유형
|
||||
|
||||
%ul
|
||||
%li
|
||||
%code Added
|
||||
새로운 기능
|
||||
%li
|
||||
%code Changed
|
||||
기존 기능의 변경사항
|
||||
%li
|
||||
%code Deprecated
|
||||
곧 지워질 기능
|
||||
%li
|
||||
%code Removed
|
||||
지금 지워진 기능
|
||||
%li
|
||||
%code Fixed
|
||||
버그 픽스
|
||||
%li
|
||||
%code Security
|
||||
취약점이 있는 경우
|
||||
|
||||
.effort
|
||||
|
||||
%h3#effort
|
||||
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
||||
changelog를 관리하는 노력을 어떻게 줄일 수 있나요?
|
||||
|
||||
%p
|
||||
<code>Unreleased</code> 섹션을 가장 위에 두어 다가올 변경사항을 추적할 수 있도록 하세요.
|
||||
|
||||
%p 이것은 두 가지 용도로 사용됩니다:
|
||||
|
||||
%ul
|
||||
%li
|
||||
사람들이 다음 릴리즈에서 기대하는 변경사항을 확인할 수 있습니다.
|
||||
%li
|
||||
릴리즈 시점에 <code>Unreleased</code> 섹션의 변경사항을 새 릴리즈 섹션으로 이동할 수 있습니다.
|
||||
|
||||
.bad-practices
|
||||
%h3#bad-practices
|
||||
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||||
changelogs가 안좋게 될 수 있습니까?
|
||||
|
||||
%p 네. 여기에 changelog가 쓸모없게 되는 몇가지 경우들이 있습니다.
|
||||
|
||||
%h4#log-diffs
|
||||
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||||
커밋 로그 차이(Commit log diffs)
|
||||
|
||||
%p
|
||||
커밋 로그 차이를 changelog로 사용하는 것은 안좋은 생각입니다:
|
||||
머지 커밋, 모호한 타이틀을 가진 커밋, 문서 변경 등 노이즈로 가득차 있습니다.
|
||||
|
||||
%p
|
||||
커밋의 목적은 소스 코드 진화의 단계를 기록하기 위함입니다.
|
||||
어떤 프로젝트는 커밋을 정리하지만, 어떤 프로젝트는 하지 않습니다.
|
||||
|
||||
%p
|
||||
changelog 기입의 목적은 종종 다수의 커밋 중에서 주목할만한 차이를
|
||||
최종 사용자에게 명확하게 전달하기 위해 문서화하는 것입니다.
|
||||
|
||||
%h4#ignoring-deprecations
|
||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||
없어질 기능들(Deprecations) 무시하기
|
||||
|
||||
%p
|
||||
사람들이 다른 버전으로 업그레이드 할 때, 언제 어떤 것이 손상될수있는지(breakable) 고통스럽게 분명해야 합니다.
|
||||
앞으로 사라질 기능들(deprecations)이 나열된 버전으로 업그레이드하고,
|
||||
더 이상 사용하지 않는 것(deprecated)을 제거한 뒤, 그 사라질 기능들이
|
||||
정말 없어진 버전으로 업데이트 하는 것이 가능해야 합니다.
|
||||
|
||||
%p
|
||||
아무 작업도 수행하지 않는다면, 없어질 기능들, 제거된 것, 모든 급격한 변화를 changelog에 남기십시오.
|
||||
|
||||
|
||||
%h4#confusing-dates
|
||||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||
날짜를 혼동하는 것
|
||||
|
||||
%p
|
||||
지역 날짜 포맷은 전세계에 걸쳐 다르고 종종 모두에게 직관적인 인간 친화적 날짜 포맷을 찾기 힘듭니다.
|
||||
<code>2017-07-17</code> 같은 날짜 포맷(연, 월, 일)의 장점은
|
||||
큰 단위부터 작은 단위의 순서를 따른다는 것입니다.
|
||||
월과 일의 위치가 뒤바뀐 어떤 포맷과 다르게, 이 포맷은 다른 날짜 포맷과 모호하게 겹치는 부분이 없습니다.
|
||||
이런 이유와 이 포맷이 #{link_to "ISO standard", iso}라는 사실이
|
||||
changelog 기입을 위해 이 날짜 포맷을 추천하는 이유입니다.
|
||||
|
||||
%aside
|
||||
안티패턴은 더 있습니다.
|
||||
= link_to "이슈 오픈하기", issues
|
||||
나 pull 요청을 통해
|
||||
안티패턴들을 모으는 것을 도와주세요.
|
||||
|
||||
.frequently-asked-questions
|
||||
%h3#frequently-asked-questions
|
||||
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
||||
자주 하는 질문
|
||||
|
||||
%h4#standard
|
||||
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
||||
changelog의 표준 포맷이 있나요?
|
||||
|
||||
%p
|
||||
없습니다. GNU changelog 스타일 가이드나 두 문단정도의 GNU NEWS '가이드라인'이 있습니다.
|
||||
하지만 둘다 부적절하거나 충분하지 않습니다.
|
||||
|
||||
%p
|
||||
이 프로젝트의 목표는
|
||||
= link_to "더 나은 changelog 규칙", changelog
|
||||
입니다.
|
||||
이것은 오픈소스 커뮤니티에서 좋은 용례를 관찰하고 모으는데서 나옵니다.
|
||||
|
||||
%p
|
||||
건강한 비판, 토론 및 개선 제안은
|
||||
= link_to "환영합니다.", issues
|
||||
|
||||
|
||||
%h4#filename
|
||||
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
||||
changelog 파일의 이름을 무엇으로 지어야 하나요?
|
||||
|
||||
%p
|
||||
<code>CHANGELOG.md</code>라고 만드세요. 어떤 프로젝트는
|
||||
<code>HISTORY</code>, <code>NEWS</code> 또는 <code>RELEASES</code>를 사용합니다.
|
||||
|
||||
%p
|
||||
changelog 파일의 이름이 무슨 상관이냐고 생각하기 쉽겠지만,
|
||||
왜 굳이 여러분의 사용자가 변경사항을 일관적으로 찾기 힘들도록 만드나요?
|
||||
|
||||
%h4#github-releases
|
||||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||||
깃허브 릴리즈는 어떻게 하나요?
|
||||
|
||||
%p
|
||||
이것은 훌륭한 이니셔티브입니다. #{link_to "릴리즈", ghr}는
|
||||
직접 릴리즈 노트를 추가하거나 어노테이션된 깃 태그 메시지를 가져와서 노트로 바꿔
|
||||
간단한 깃 태그(예를 들어 <code>v1.0.0</code> 태그
|
||||
)를 풍부한 릴리즈 노트로 전환시키는데 사용될 수 있습니다.
|
||||
|
||||
%p
|
||||
깃허브 릴리즈는 이동 불가능한 깃허브 컨텍스트 내에서만 표시되는 changelog를 생성합니다.
|
||||
Keep a Changelog 포맷처럼 보이게 만드는 게 가능하지만, 좀 더 복잡해지는 경향이 있습니다.
|
||||
|
||||
%p
|
||||
전형적인 대문자 파일들과 달리(<code>README</code>, <code>CONTRIBUTING</code>, 등),
|
||||
깃허브 릴리즈의 현재 버전은 최종 사용자가 거의 찾아볼 수 없습니다.
|
||||
다른 사소한 이슈는 인터페이스가 현재 각 릴리즈 사이에 로그를 커밋할 수 있는 링크를 제공하지 않는 것입니다.
|
||||
|
||||
%h4#automatic
|
||||
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
||||
Changelog를 자동으로 파싱할 수 있나요?
|
||||
|
||||
%p
|
||||
사람들이 대단히 다양한 포맷과 파일 이름을 따르기 때문에 어렵습니다.
|
||||
|
||||
%p
|
||||
#{link_to "Vandamme", vandamme}은 #{link_to "Gemnasium", gemnasium} 팀에 의해
|
||||
생성된 루비잼이고 많은(전부는 아니고) 오픈소스 프로젝트의 changelog를 파싱합니다.
|
||||
|
||||
|
||||
%h4#yanked
|
||||
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
||||
삭제된 릴리즈(Yanked release)는 어떻게 하나요?
|
||||
|
||||
%p
|
||||
삭제된(Yanked) 릴리즈는 심각한 버그나 보안 이슈 때문에 소스에서 들어내버린 버전을 말합니다.
|
||||
대게 이런 버전은 changelog에 아예 나오지도 않지만, 나와야 합니다. 이것이 삭제된 릴리즈를
|
||||
표시하는 방법입니다:
|
||||
|
||||
%p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
|
||||
|
||||
%p
|
||||
<code>[YANKED]</code> 태그가 요란한 이유가 있습니다.
|
||||
사람들이 알아차리는 것이 중요합니다. 대괄호 안에 있기 때문에 프로그래밍적으로 파싱하기에도 용이합니다.
|
||||
|
||||
|
||||
%h4#rewrite
|
||||
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
||||
changelog를 다시 써야하나요?
|
||||
|
||||
%p
|
||||
물론입니다. changelog를 개선할 좋은 이유는 항상 있습니다. 저는 정기적으로
|
||||
changelog가 관리되지 않는 오픈소스에 빠진 릴리즈를 추가하기 위해 pull request를 오픈합니다.
|
||||
|
||||
%p
|
||||
어떤 버전의 급격한 변화에 대해 언급하는 것을 잊은 것을 발견할 수도 있습니다.
|
||||
이 경우엔 changelog를 업데이트하는 것이 당연히 중요합니다.
|
||||
|
||||
|
||||
%h4#contribute
|
||||
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
||||
어떻게 기여할 수 있나요?
|
||||
|
||||
%p
|
||||
이 문서가 <strong>진리</strong>는 아닙니다. 이것은 제가 모은 정보와 예제들과 함께
|
||||
신중하게 고려한 의견입니다.
|
||||
|
||||
%p
|
||||
왜냐하면 우리 커뮤니티가 공감대를 형성하기를 원하기 때문입니다. 저는 최종결과 못지않게 토론도 중요하다고 생각합니다.
|
||||
|
||||
%p
|
||||
그러니 <strong>#{link_to "참여", gh}</strong>를 부탁합니다.
|
||||
|
||||
.press
|
||||
%h3 대화
|
||||
%p
|
||||
왜 관리자와 기여자가 changelog를 신경써야하는지, 또한 이 프로젝트를 하게된 동기에 대해 이야기하기 위해
|
||||
#{link_to "The Changelog 팟캐스트", thechangelog}에 다녀왔습니다.
|
||||
@ -36,7 +36,7 @@
|
||||
= stylesheet_link_tag 'application'
|
||||
- else
|
||||
= stylesheet_link_tag 'legacy'
|
||||
= javascript_include_tag 'all'
|
||||
= javascript_include_tag 'all', defer: true
|
||||
|
||||
%body
|
||||
%article
|
||||
|
||||
299
source/nl/1.0.0/index.html.haml
Normal file
299
source/nl/1.0.0/index.html.haml
Normal file
@ -0,0 +1,299 @@
|
||||
---
|
||||
description: Keep a Changelog
|
||||
title: Keep a Changelog
|
||||
language: nl
|
||||
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 = "https://semver.org/"
|
||||
- shields = "https://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 Houd een Changelog bij
|
||||
%h2 Laat je vrienden geen git logs in changelogs dumpen.
|
||||
|
||||
= link_to changelog do
|
||||
Versie
|
||||
%strong= current_page.metadata[:page][:version]
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
|
||||
.answers
|
||||
%h3#what
|
||||
%a.anchor{ href: "#what", aria_hidden: "true" }
|
||||
Wat is een changelog?
|
||||
|
||||
%p
|
||||
Een changelog is een bestand met een zorgvuldig samengestelde, chronologische lijst
|
||||
van noemenswaardige aanpassingen voor elke versie van een project.
|
||||
|
||||
%h3#why
|
||||
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||||
Waarom een changelog bijhouden?
|
||||
|
||||
%p
|
||||
Om het makkelijker te maken voor gebruikers en programmeurs om precies te zien welke
|
||||
noemenswaardige aanpassingen er gedaan zijn tussen elke release (of versie) van het project.
|
||||
|
||||
%h3#who
|
||||
%a.anchor{ href: "#who", aria_hidden: "true" }
|
||||
Wie heeft een changelog nodig?
|
||||
|
||||
%p
|
||||
Mensen hebben het nodig. Of het nu consumenten of ontwikkelaars zijn, eindgebruikers van
|
||||
software zijn mensen die er om geven wat er in de software zit die ze gebruiken.
|
||||
Als de software veranderd, wil men weten wat en hoe.
|
||||
|
||||
.good-practices
|
||||
%h3#how
|
||||
%a.anchor{ href: "#how", aria_hidden: "true" }
|
||||
Hoe maak ik een goed changelog?
|
||||
|
||||
%h4#principles
|
||||
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
||||
Richtlijnen
|
||||
|
||||
%ul
|
||||
%li
|
||||
Changelogs zijn <em>voor mensen</em>, niet voor machines.
|
||||
%li
|
||||
Er zou een vermelding moeten zijn voor elke versie.
|
||||
There should be an entry for every single version.
|
||||
%li
|
||||
Aanpassingen van het zelfde type moeten gegroepeerd worden.
|
||||
%li
|
||||
Versies en secties zouden linkbaar moeten zijn.
|
||||
%li
|
||||
De laatste versie staat bovenaan.
|
||||
%li
|
||||
De release datum van elke versie word weergegeven.
|
||||
%li
|
||||
Geef aan of je #{link_to "Semantic Versioning", semver} gebruikt.
|
||||
|
||||
%a.anchor{ href: "#types", aria_hidden: "true" }
|
||||
%h4#types Types of changes
|
||||
|
||||
%ul
|
||||
%li
|
||||
%code Added
|
||||
voor nieuwe functionaliteit.
|
||||
%li
|
||||
%code Changed
|
||||
voor aanpassingen aan bestaande functionaliteit.
|
||||
%li
|
||||
%code Deprecated
|
||||
voor functionaliteit die binnenkort komt te vervallen.
|
||||
%li
|
||||
%code Removed
|
||||
voor functionaliteit die vanaf nu vervallen is.
|
||||
%li
|
||||
%code Fixed
|
||||
voor bug fixes.
|
||||
%li
|
||||
%code Security
|
||||
voor aanpassingen met betrekking tot veiligheid.
|
||||
|
||||
.effort
|
||||
|
||||
%h3#effort
|
||||
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
||||
Hoe kan ik, met zo min mogelijk moeite, een changelog bij houden?
|
||||
|
||||
%p
|
||||
Houd bovenin een <code>Unreleased</code> sectie bij met aanpassingen voor de komende release.
|
||||
|
||||
%p Dit heeft twee doelen:
|
||||
|
||||
%ul
|
||||
%li
|
||||
Mensen kunnen zien wat te verwachten in de aankomende release.
|
||||
%li
|
||||
Als je een release doet kan je eenvoudig de <code>Unreleased</code> sectie
|
||||
aanpassen naar een nieuwe release sectie.
|
||||
|
||||
.bad-practices
|
||||
%h3#bad-practices
|
||||
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||||
Kan een changelog slecht zijn?
|
||||
|
||||
%p Ja. Hier een paar manieren waarop je een changelog behoorlijk onbruikbaar kan maken.
|
||||
|
||||
%h4#log-diffs
|
||||
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||||
Commit log diffs
|
||||
|
||||
%p
|
||||
Commit log diffs gebruiken als een changelog is een slecht idee:
|
||||
ze staan vol met ruis. Denk bijvoorbeeld aan merge commits, commits met
|
||||
onduidelijke titels, documentatie aanpassingen etc.
|
||||
|
||||
%p
|
||||
Het doel van een commit bericht is om één enkele stap in de evolutie van de
|
||||
code te beschrijven.
|
||||
|
||||
%p
|
||||
Het doel van een changelog is om noemenswaardige aanpassingen te documenteren,
|
||||
vaak over meerdere commits, en om deze duidelijk naar de eindgebruiker te communiceren.
|
||||
|
||||
%h4#ignoring-deprecations
|
||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||
Deprecations negeren
|
||||
|
||||
%p
|
||||
Wanneer mensen upgraden van de ene naar de andere versie,
|
||||
moet het overduidelijk zijn als er iets niet meer zal werken.
|
||||
Het moet mogelijk zijn om te upgraden naar een versie met deprications,
|
||||
vervolgens de deprications weg te halen, en vervolgens
|
||||
de upgrade kunnen doen naar de versie waar de deprications removals zijn geworden.
|
||||
|
||||
%p
|
||||
Geef altijd op zijn minst de deprications, removals en changes met grote impact aan in je changelog.
|
||||
|
||||
%h4#confusing-dates
|
||||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||
Verwarrende datums
|
||||
|
||||
%p
|
||||
Datum notaties verschillen van land tot land, en het is vaak moeilijk om
|
||||
een notatie te vinden die makkelijk te lezen is en intuitief is voor iedereen.
|
||||
|
||||
Het voordeel van de notatie <code>2017-07-17</code> is dat het jaar, maand en dag
|
||||
op volgorde van grootte laat zien. Daarom, en het feit dat dit een #{link_to "ISO standaard", iso}
|
||||
is, is dit de aanbevolen datum notatie voor changelog releases.
|
||||
|
||||
%aside
|
||||
Dit is niet alles. Help mij antipatterns te verzamelen door
|
||||
= link_to "een issue", issues
|
||||
of een pull request aan te maken.
|
||||
|
||||
.frequently-asked-questions
|
||||
%h3#frequently-asked-questions
|
||||
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
||||
Veel Gestelde Vragen
|
||||
|
||||
%h4#standard
|
||||
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
||||
Is er een standaard changelog template?
|
||||
|
||||
%p
|
||||
Niet echt. Er is de GNU changelog style guide, en het twee paragrafen lange GNU NEWS bestand "richtlijnen".
|
||||
Beiden zijn niet volledig genoeg.
|
||||
|
||||
%p
|
||||
Dit project poogt
|
||||
= link_to "een betere changelog standaard", changelog
|
||||
te creëren. Dit op basis van "good practices" uit de open source wereld.
|
||||
|
||||
%p
|
||||
Opbouwende kritiek, discussie en suggesties voor verbetering
|
||||
= link_to "zijn welkom.", issues
|
||||
|
||||
|
||||
%h4#filename
|
||||
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
||||
Wat zou de changelog bestandsnaam moeten zijn?
|
||||
|
||||
%p
|
||||
Noem het <code>CHANGELOG.md</code>. Sommige projecten gebruiken
|
||||
<code>HISTORY</code>, <code>NEWS</code> of <code>RELEASES</code>.
|
||||
|
||||
%p
|
||||
Je kan denken dat de bestandsnaam niet heel belangrijk is,
|
||||
maar waarom zou je het de eindgebruikers moeilijker maken om de changelog te vinden?
|
||||
|
||||
%h4#github-releases
|
||||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||||
Wat denk je van GitHub Releases?
|
||||
|
||||
%p
|
||||
Het is een goed initiatief. #{link_to "Releases", ghr} kan gebruikt worden
|
||||
om simpele git tags (bijvoorbeeld een tag met de naam <code>v1.0.0</code>)
|
||||
te veranderen in uitgebreide release notes door deze handmatig toe te voegen of
|
||||
door geannoteerde git tag berichten te gebruiken om release notes te genereren.
|
||||
|
||||
%p
|
||||
GitHub Releases maken changelog wat alleen getoond kan worden aan gebruikers
|
||||
binnen de context van GitHub. Het is mogelijk om deze dicht bij het format
|
||||
te krijgen wat wij hier promoten, maar er zal iets meer werk voor nodig zijn.
|
||||
|
||||
%p
|
||||
De huidige versie van GitHub releases is naar mijn mening niet
|
||||
echt goed vindbaar voor gebruikers, in tegenstelling tot de typische
|
||||
bestanden die in een naam in hoofdletters hebben
|
||||
(<code>README</code>, <code>CONTRIBUTING</code>, etc.).
|
||||
Een ander knelpunt is dat de interface geen links toestaat naar
|
||||
commit logs van elke release.
|
||||
|
||||
%h4#automatic
|
||||
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
||||
Kunnen changelogs automatisch geparsed worden?
|
||||
|
||||
%p
|
||||
Dat is lasig, mensen gebruiken immers veel verschillende formats en bestandsnamen.
|
||||
|
||||
%p
|
||||
#{link_to "Vandamme", vandamme} is een Ruby gem van het
|
||||
#{link_to "Gemnasium", gemnasium} team wat de changelogs van veel (maar niet alle)
|
||||
open source projecten kan parsen.
|
||||
|
||||
|
||||
%h4#yanked
|
||||
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
||||
Wat doen we met teruggetrokken (yanked) releases?
|
||||
|
||||
%p
|
||||
Teruggetrokken releases zijn versies die teruggetrokken zijn als gevolg
|
||||
van een serieuze bug of beveiligings probleem. Vaak zijn ze niet eens te zien in
|
||||
de changelogs. Dat zou wel moeten. Zo zou je een teruggetrokken release moeten tonen:
|
||||
|
||||
%p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
|
||||
|
||||
%p
|
||||
De <code>[YANKED]</code> tag is in hoofdletters voor een reden. Het is belangrijk
|
||||
dat mensen dit zien. Omdat het tussen blokhaken genoteerd is, is het ook makkelijker
|
||||
automatisch te parsen.
|
||||
|
||||
|
||||
%h4#rewrite
|
||||
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
||||
Mag je een changelog aanpassen/herschrijven?
|
||||
|
||||
%p
|
||||
Natuurlijk. Er zijn goede redenen om een changelog te verbeteren.
|
||||
Ik open regelmatig een pull request om missende releases toe te
|
||||
voegen aan open source projecten met een slecht onderhouden changelog.
|
||||
|
||||
%p
|
||||
Het kan ook zo zijn dat je ontdekt dat je een belangrijke aanpassing niet
|
||||
vermeld hebt in je changelog. Het is dan natuurlijk zaak om dit alsnog
|
||||
in je changelog te vermelden.
|
||||
|
||||
%h4#contribute
|
||||
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
||||
Hoe kan ik bijdragen?
|
||||
|
||||
%p
|
||||
Dit document is niet de <strong>waarheid</strong>; het is mijn
|
||||
weloverwogen mening, samen met wat informatie en voorbeelden die ik verzameld heb.
|
||||
|
||||
%p
|
||||
Dit heb ik gedaan omdat ik wil dat de programmeer gemeenschap een consensus bereikt.
|
||||
Ik denk dat de discussie net zo belangrijk is als het eindresultaat.
|
||||
|
||||
%p
|
||||
Dus <strong>#{link_to "alle hulp is welkom", gh}</strong>.
|
||||
|
||||
.press
|
||||
%h3 Conversaties
|
||||
%p
|
||||
Ik was te gast bij #{link_to "The Changelog podcast", thechangelog} om te praten over
|
||||
waarom een changelog belangrijk is programmeurs, en over mijn motivatie achter dit project.
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
description: Prowadź Changelog
|
||||
title: Prowadź Changelog
|
||||
language: pl-PL
|
||||
language: pl
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
@ -37,7 +37,7 @@ version: 0.3.0
|
||||
- Prostota dodawania linków do każdego rozdziału (dlatego używa się Markdown zamiast prostego tekstu).
|
||||
- Jeden podrozdział dla każdej wersji.
|
||||
- Wyszczególniaj wydania w odwrotnym porządku chronologicznym (najnowsza na górze).
|
||||
- Wszystkie daty zapisuj w formacie `YYYY-MM-DD`. (Przykład: `2012-06-02` dla `2 czerwca 2012 r.`). To [rozsądny](http://xkcd.com/1179/), niezależny od języka międzynarodowy format.
|
||||
- Wszystkie daty zapisuj w formacie `YYYY-MM-DD`. (Przykład: `2012-06-02` dla `2 czerwca 2012 r.`). To [rozsądny](https://xkcd.com/1179/), niezależny od języka międzynarodowy format.
|
||||
- Zawsze określaj, czy projekt jest zgodny z [Semantycznym Wersjonowaniem][semver].
|
||||
- Każda wersja powinna:
|
||||
- Zawierać datę w wyżej wymienionym formacie.
|
||||
@ -138,7 +138,7 @@ version: 0.3.0
|
||||
[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/
|
||||
[semver]: https://semver.org/
|
||||
[shields]: https://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
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 = "https://semver.org/"
|
||||
- shields = "https://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.
|
||||
@ -50,7 +50,7 @@ version: 0.3.0
|
||||
- Lista as versões publicadas em ordem cronológica decrescente (mais novo em
|
||||
cima).
|
||||
- Usa todas as datas no formato `AAAA-MM-DD`. (Exemplo: `2012-06-02` para
|
||||
`2 de Junho de 2012`.) É internacional, [sensato](http://xkcd.com/1179/), e
|
||||
`2 de Junho de 2012`.) É internacional, [sensato](https://xkcd.com/1179/), e
|
||||
independente de língua.
|
||||
- Menciona explicitamente se o projeto segue o [Versionamento Semântico][semver].
|
||||
- Cada versão deve:
|
||||
@ -200,7 +200,7 @@ version: 0.3.0
|
||||
[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/
|
||||
[semver]: https://semver.org/
|
||||
[shields]: https://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
|
||||
311
source/pt-BR/1.0.0/index.html.haml
Normal file
311
source/pt-BR/1.0.0/index.html.haml
Normal file
@ -0,0 +1,311 @@
|
||||
---
|
||||
description: Mantenha um Changelog
|
||||
title: Mantenha um Changelog
|
||||
language: pt-BR
|
||||
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 = "https://semver.org/"
|
||||
- shields = "https://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 Mantenha um Changelog
|
||||
%h2 Não deixe seus amigos despejarem logs de commits no Changelog
|
||||
|
||||
= link_to changelog do
|
||||
Version
|
||||
%strong= current_page.metadata[:page][:version]
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
|
||||
.answers
|
||||
%h3#what
|
||||
%a.anchor{ href: "#what", aria_hidden: "true" }
|
||||
O que é um changelog?
|
||||
|
||||
%p
|
||||
Um changelog é um arquivo que contém uma lista selecionada, ordenada
|
||||
cronologicamente, de mudanças significativas para cada versão de um projeto.
|
||||
|
||||
%h3#why
|
||||
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||||
Por que manter um changelog?
|
||||
|
||||
%p
|
||||
Para facilitar que usuários e contribuidores vejam precisamente quais
|
||||
mudanças significativas foram realizadas entre cada versão publicada de
|
||||
um projeto.
|
||||
|
||||
%h3#who
|
||||
%a.anchor{ href: "#who", aria_hidden: "true" }
|
||||
Quem precisa de um changelog?
|
||||
|
||||
%p
|
||||
Pessoas precisam. Seja consumidores ou desenvolvedores,
|
||||
os usuários finais de softwares são seres humanos
|
||||
que se preocupam com o que está no software. Quando
|
||||
o software muda, as pessoas querem saber por que e como.
|
||||
|
||||
.good-practices
|
||||
%h3#how
|
||||
%a.anchor{ href: "#how", aria_hidden: "true" }
|
||||
Como fazer um bom changelog?
|
||||
|
||||
%h4#principles
|
||||
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
||||
Princípios fundamentais
|
||||
|
||||
%ul
|
||||
%li
|
||||
Changelogs são <em>para humanos</em>, não máquinas.
|
||||
%li
|
||||
Deve haver uma entrada para cada versão.
|
||||
%li
|
||||
Alterações do mesmo tipo devem ser agrupadas.
|
||||
%li
|
||||
Versões e seções devem ser vinculáveis (com links).
|
||||
%li
|
||||
A versão mais recente vem em primeiro lugar.
|
||||
%li
|
||||
A data de lançamento de cada versão é exibida.
|
||||
%li
|
||||
Mencione se você segue o #{link_to "versionamento semântico", semver}.
|
||||
|
||||
%a.anchor{ href: "#types", aria_hidden: "true" }
|
||||
%h4#types Tipos de mudanças
|
||||
|
||||
%ul
|
||||
%li
|
||||
%code Added/Adicionado
|
||||
para novos recursos.
|
||||
%li
|
||||
%code Changed/Modificado
|
||||
para alterações em recursos existentes.
|
||||
%li
|
||||
%code Deprecated/Obsoleto
|
||||
para recursos que serão removidos nas próximas versões.
|
||||
%li
|
||||
%code Removed/Removido
|
||||
para recursos removidos nesta versão.
|
||||
%li
|
||||
%code Fixed/Corrigido
|
||||
para qualquer correção de bug.
|
||||
%li
|
||||
%code Security/Segurança
|
||||
em caso de vulnerabilidades.
|
||||
|
||||
.effort
|
||||
|
||||
%h3#effort
|
||||
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
||||
Como eu posso minimizar o esforço exigido para manter um changelog?
|
||||
|
||||
%p
|
||||
Mantenha sempre uma seção <code>Não publicado</code> no topo para manter o controle das novas mudanças.
|
||||
|
||||
%p Isso serve a dois propósitos:
|
||||
|
||||
%ul
|
||||
%li
|
||||
As pessoas podem ver quais mudanças elas podem esperar em publicações futuras.
|
||||
%li
|
||||
No momento da publicação, você apenas tem de mudar a seção
|
||||
<code>Não publicado</code> para o número de versão e adicionar uma
|
||||
nova seção <code>Não publicado</code> no topo.
|
||||
|
||||
.bad-practices
|
||||
%h3#bad-practices
|
||||
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||||
Os changelogs podem ser ruins?
|
||||
|
||||
%p Sim. Aqui estão algumas maneiras pelas quais eles podem ser inúteis.
|
||||
|
||||
%h4#log-diffs
|
||||
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||||
Usar um registro de alterações automático
|
||||
|
||||
%p
|
||||
Usar um registro de alterações automático é uma má ideia: eles estão
|
||||
cheios de bagunça. Coisas como solicitação de mesclagem, envio com títulos
|
||||
estranhos, alterações de documentação, etc.
|
||||
|
||||
%p
|
||||
O propósito de um commit é documentar a etapa na evolução do código
|
||||
fonte. Alguns projetos limpam os commits, outros não.
|
||||
|
||||
%p
|
||||
O propósito de uma entrada de changelog é documentar as diferenças
|
||||
notáveis, muitas vezes de múltiplos commits, para comunicar de forma
|
||||
clara os usuários.
|
||||
|
||||
%h4#ignoring-deprecations
|
||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||
Ignorando depreciações
|
||||
|
||||
%p
|
||||
Quando pessoas atualizam de uma versão para outra, deve ficar muitíssimo claro
|
||||
quando algo vai quebrar. Deve ser possível atualizar para uma versão
|
||||
com depreciações listadas, remova o que é obsoleto, depois atualize
|
||||
para a versão onde as depreciações se tornam remoções.
|
||||
|
||||
%p
|
||||
Se você não fizer mais nada, liste no seu changelog as depreciações,
|
||||
remoções e quaisquer mudanças que gerem falhas.
|
||||
|
||||
%h4#confusing-dates
|
||||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||
Datas confusas
|
||||
|
||||
%p
|
||||
Os formatos regionais de data variam em todo o mundo e muitas vezes
|
||||
é difícil encontrar um formato de data amigável que seja intuitivo para todos.
|
||||
A vantagem das datas formatadas como <code>2017-07-17</code> é que elas seguem
|
||||
a ordem da maior para a menor unidade de tempo: ano, mês e dia. Este formato
|
||||
também não se confunde de maneira ambígua com outros formatos de data, ao
|
||||
contrário de alguns formatos regionais que alteram a posição dos números do mês
|
||||
e dia. Esses motivos, e o fato de ser um formato de data suportado pela
|
||||
#{link_to "norma ISO", iso} são as razões para ele ser o formato de data
|
||||
recomendado para as entradas do changelog.
|
||||
|
||||
%aside
|
||||
Tem mais. Me ajude a colecionar essas más práticas
|
||||
= link_to "enviando uma dúvida", issues
|
||||
ou pedindo mudanças.
|
||||
|
||||
.frequently-asked-questions
|
||||
%h3#frequently-asked-questions
|
||||
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
||||
Perguntas frequentes
|
||||
|
||||
%h4#standard
|
||||
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
||||
Existe um padrão para o formato do changelog?
|
||||
|
||||
%p
|
||||
Na verdade não. Existe o guia de estilo de changelog do GNU
|
||||
ou o "guia" de dois parágrafos do GNU NEWS. Ambos são inadequados ou
|
||||
insuficientes.
|
||||
|
||||
%p
|
||||
Este projeto pretende ser #{link_to "uma convenção de changelog melhor.", changelog}
|
||||
Ele vem de observar e coletar as boas práticas em código aberto da
|
||||
comunidade.
|
||||
|
||||
%p
|
||||
Críticas saudáveis, discussões e sugestões de melhorias
|
||||
= link_to "são bem-vindas.", issues
|
||||
|
||||
%h4#filename
|
||||
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
||||
Qual nome o arquivo changelog deve ter?
|
||||
|
||||
%p
|
||||
Chame-o <code>CHANGELOG.md</code>. Alguns projetos usam
|
||||
<code>HISTORY</code>, <code>NEWS</code> ou <code>RELEASES</code>.
|
||||
|
||||
%p
|
||||
Embora seja fácil pensar que o nome do seu arquivo changelog
|
||||
não importa muito, por que tornar mais difícil para seus usuários
|
||||
finais encontrarem consistentemente mudanças notáveis?
|
||||
|
||||
%h4#github-releases
|
||||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||||
E sobre o GitHub Releases?
|
||||
|
||||
%p
|
||||
É uma grande iniciativa. #{link_to "Lançamentos", ghr} podem ser usados
|
||||
para converter simples marcadores do git (por exemplo, um
|
||||
marcador chamado <code>v1.0.0</code>) em notas de versão ricas,
|
||||
adicionando manualmente notas de versão ou pode puxar as mensagens
|
||||
anotadas no marcador do git e transformá-las em notas.
|
||||
|
||||
%p
|
||||
GitHub Releases cria um changelog não portátil
|
||||
que só pode ser exibido para usuários no contexto do GitHub.
|
||||
É possível fazê-los parecer muito como o formato
|
||||
Keep a Changelog, mas tende a ser um pouco mais complicado.
|
||||
|
||||
%p
|
||||
A versão atual do GitHub Releases não é facilmente descoberta
|
||||
por usuários finais, ao contrário dos arquivos maiúsculos típicos
|
||||
(<code>README</code>, <code>CONTRIBUTING</code>, etc.). Outro
|
||||
problema de menor magnitude é que a interface atualmente não oferece
|
||||
links para confirmar alterações entre cada lançamento.
|
||||
|
||||
%h4#automatic
|
||||
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
||||
Os changelogs podem ser criados automaticamente?
|
||||
|
||||
%p
|
||||
É difícil, porque as pessoas seguem formatos e nomes de arquivos
|
||||
totalmente diferentes.
|
||||
|
||||
%p
|
||||
#{link_to "Vandamme", vandamme} é um gem Ruby criado pelo
|
||||
time #{link_to "Gemnasium", gemnasium} e que analisa muitas
|
||||
(mas não todas) alterações de projetos de código aberto.
|
||||
|
||||
%h4#yanked
|
||||
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
||||
E o lançamentos removidos?
|
||||
|
||||
%p
|
||||
Lançamentos removidos são versões que foram retiradas por causa de
|
||||
problemas sérios ou falhas de segurança. Muitas vezes essas versões
|
||||
nem aparecem no histórico de alterações. Eles deviam. É assim que
|
||||
você deve exibi-los:
|
||||
|
||||
%p <code>## 0.0.5 - 2014-12-13 [REMOVIDO]</code>
|
||||
|
||||
%p
|
||||
O marcador <code>[REMOVIDO]</code> está em caixa alta por uma razão.
|
||||
É importante que as pessoas o percebam. Já que está entre
|
||||
colchetes, também fica mais fácil de ser analisado programaticamente.
|
||||
|
||||
%h4#rewrite
|
||||
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
||||
Você deve reescrever um changelog?
|
||||
|
||||
%p
|
||||
Claro. Sempre existe razão para melhorar um changelog.
|
||||
Eu regularmente solicito alterações em projetos de código livre que
|
||||
possuem changelogs não mantidos para adicionar lançamentos
|
||||
que não estão presentes nestes.
|
||||
|
||||
%p
|
||||
Também é possível que você descubra que você esqueceu de abordar
|
||||
uma mudança abrupta nas notas para uma versão.
|
||||
Obviamente é importante que você atualize seu changelog neste caso.
|
||||
|
||||
%h4#contribute
|
||||
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
||||
Como eu posso ajudar?
|
||||
|
||||
%p
|
||||
Esse documento não é uma <strong>verdade absoluta</strong>; É minha
|
||||
opinião cuidadosamente considerada, juntamente com informações e
|
||||
exemplos que eu reuni.
|
||||
|
||||
%p
|
||||
Isso porque o que eu quero é que nossa comunidade chegue a um consenso.
|
||||
Eu acredito que a discussão é tão importante quanto o resultado final.
|
||||
|
||||
%p
|
||||
Então, por favor <strong>#{link_to "contribua", gh}</strong>.
|
||||
|
||||
.press
|
||||
%h3 Discussões
|
||||
%p
|
||||
Eu fui no #{link_to "The Changelog podcast", thechangelog}
|
||||
para falar sobre por que os mantenedores e contribuidores devem se
|
||||
preocupar com os changelogs, e também sobre as motivações
|
||||
por trás desse projeto.
|
||||
@ -51,7 +51,7 @@ version: 0.3.0
|
||||
- Релизы перечислены в обратном хронологическом порядке (самые новые –
|
||||
сверху).
|
||||
- Пишите все даты в формате `YYYY-MM-DD`. (Например: `2012-06-02` для даты `2
|
||||
июня 2012`.) Он международный, [рациональный](http://xkcd.com/1179/), и
|
||||
июня 2012`.) Он международный, [рациональный](https://xkcd.com/1179/), и
|
||||
независим от языка.
|
||||
- Ясно указывает, использует ли проект [Семантическое
|
||||
Версионирование][semver].
|
||||
@ -206,7 +206,7 @@ version: 0.3.0
|
||||
[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/
|
||||
[semver]: https://semver.org/
|
||||
[shields]: https://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
|
||||
@ -9,8 +9,8 @@ version: 1.0.0
|
||||
- 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/"
|
||||
- semver = "https://semver.org/"
|
||||
- shields = "https://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"
|
||||
|
||||
303
source/sk/1.0.0/index.html.haml
Normal file
303
source/sk/1.0.0/index.html.haml
Normal file
@ -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 = "https://semver.org/"
|
||||
- shields = "https://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.
|
||||
@ -41,7 +41,7 @@ version: 0.3.0
|
||||
- Enostaven za povezavo kateri koli sekciji (torej Markdown pred golim besedilom).
|
||||
- Ena pod-sekcija na verzijo.
|
||||
- Seznam izdaj v obratnem kronološkem vrstnem redu (najnovejše na vrhu).
|
||||
- Zapis vseh datumov v `YYYY-MM-DD` formatu. (Na primer: `2012-06-02` za `2. junij 2012`.) Je mednarnodno, [smiselno](http://xkcd.com/1179/) in neodvisno od jezika.
|
||||
- Zapis vseh datumov v `YYYY-MM-DD` formatu. (Na primer: `2012-06-02` za `2. junij 2012`.) Je mednarnodno, [smiselno](https://xkcd.com/1179/) in neodvisno od jezika.
|
||||
- Eksplicitna omemba ali projekt sledi [semantičnim verzijam][semver].
|
||||
- Vsaka verzija bi morala:
|
||||
- Imeti seznam njenih datumov izdaje v zgornjem formatu.
|
||||
@ -176,7 +176,7 @@ version: 0.3.0
|
||||
[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/
|
||||
[semver]: https://semver.org/
|
||||
[shields]: https://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
|
||||
@ -43,7 +43,7 @@ version: 0.3.0
|
||||
- Listar utgåvor i omvänd kronologisk ordning (nyast högst upp).
|
||||
- Anger alla datum på formatet `YYYY-MM-DD`
|
||||
(exempel: `2012-06-02` för 2:a juni 2012). Det är internationellt,
|
||||
[förnuftigt](http://xkcd.com/1179/) och språkoberoende.
|
||||
[förnuftigt](https://xkcd.com/1179/) och språkoberoende.
|
||||
- Anger uttryckligen om projektet följer [Semantisk versionshantering][SemVer].
|
||||
- Varje version bör:
|
||||
- Ange datum då utgåvan släpptes på formatet angivet ovan.
|
||||
@ -180,7 +180,7 @@ version: 0.3.0
|
||||
[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/
|
||||
[semver]: https://semver.org/
|
||||
[shields]: https://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
|
||||
@ -9,8 +9,8 @@ version: 1.0.0
|
||||
- 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/"
|
||||
- semver = "https://semver.org/"
|
||||
- shields = "https://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"
|
||||
|
||||
@ -39,7 +39,7 @@ version: 0.3.0
|
||||
- Kolayca bölümler arası bağlantı kurulabilmelidir. (Bu yüzden yalın metin yerine markdown)
|
||||
- Her sürüm için bir alt bölüm içermelidir.
|
||||
- Dağıtımları tersine tarih sırası ile listemelidir. (En yeni en üstte)
|
||||
- Tüm tarihler `YYYY-AA-GG` biçiminde olmalıdır. (Örneğin `2 Haziran 2012` için `2012-06-02`) Uluslararasıdır, [anlamlıdır](http://xkcd.com/1179/), ve lisan bağımsızdır.
|
||||
- Tüm tarihler `YYYY-AA-GG` biçiminde olmalıdır. (Örneğin `2 Haziran 2012` için `2012-06-02`) Uluslararasıdır, [anlamlıdır](https://xkcd.com/1179/), ve lisan bağımsızdır.
|
||||
- [Anlamsal sürümleme][semver]nin desteklenip desteklenmediğini özellikle belirtilmelidir.
|
||||
- Her sürümde olması gerekenler:
|
||||
- Üstteki biçimde dağıtım tarihi.
|
||||
@ -171,7 +171,7 @@ version: 0.3.0
|
||||
[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/
|
||||
[semver]: https://semver.org/
|
||||
[shields]: https://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
|
||||
@ -9,8 +9,8 @@ version: 1.0.0
|
||||
- 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/"
|
||||
- semver = "https://semver.org/"
|
||||
- shields = "https://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"
|
||||
|
||||
@ -40,7 +40,7 @@ version: 0.3.0
|
||||
- 一个版本对应一个章节。
|
||||
- 最新的版本在上，最老的在下面。
|
||||
- 所有日期采用'YYYY-MM-DD'这种规范。（例如北京奥运会的2008年8月8日是2008-08-08）这个是国际通用，任何语言
|
||||
都能理解的，并且还被[xkcd](http://xkcd.com/1179/)推荐呢！
|
||||
都能理解的，并且还被[xkcd](https://xkcd.com/1179/)推荐呢！
|
||||
- 标出来是否遵守[语义化版本格式][semver]
|
||||
- 每一个软件的版本必须：
|
||||
- 标明日期（要用上面说过的规范）
|
||||
@ -141,7 +141,7 @@ version: 0.3.0
|
||||
[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/lang/zh-CN/
|
||||
[shields]: http://shields.io/
|
||||
[semver]: https://semver.org/lang/zh-CN/
|
||||
[shields]: https://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
|
||||
@ -9,8 +9,8 @@ version: 1.0.0
|
||||
- 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/"
|
||||
- semver = "https://semver.org/"
|
||||
- shields = "https://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"
|
||||
|
||||
@ -40,7 +40,7 @@ version: 0.3.0
|
||||
- 一個版本對應一個章節。
|
||||
- 最新的版本在上面，最舊的在下面。
|
||||
- 所有日期採用 'YYYY-MM-DD' 這種規範。（例如北京奧運會的 2008 年 8 月 8 日是 2008-08-08）這個是國際通用，任何語言
|
||||
都能理解的，並且還被 [xkcd](http://xkcd.com/1179/) 推薦呢！
|
||||
都能理解的，並且還被 [xkcd](https://xkcd.com/1179/) 推薦呢！
|
||||
- 標出來是否遵守[語義化版本格式][semver]
|
||||
- 每一個軟體的版本必須：
|
||||
- 標明日期（要用上面說過的規範）
|
||||
@ -141,7 +141,7 @@ version: 0.3.0
|
||||
[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/lang/zh-CN/
|
||||
[shields]: http://shields.io/
|
||||
[semver]: https://semver.org/lang/zh-CN/
|
||||
[shields]: https://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme
|
||||
|
||||
266
source/zh-TW/1.0.0/index.html.haml
Normal file
266
source/zh-TW/1.0.0/index.html.haml
Normal file
@ -0,0 +1,266 @@
|
||||
---
|
||||
description: 如何維護更新日誌
|
||||
title: 如何維護更新日誌
|
||||
language: zh-TW
|
||||
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 = "https://semver.org/lang/zh-TW/"
|
||||
- shields = "https://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/"
|
||||
- gnu_changelog_styleguide = "https://www.gnu.org/prep/standards/html_node/Change-Logs.html"
|
||||
- gnu_the_news = "https://www.gnu.org/prep/standards/html_node/NEWS-File.html"
|
||||
|
||||
.header
|
||||
.title
|
||||
%h1 如何維護更新日誌
|
||||
%h2 更新日誌絕對不應該只是 git log 的堆砌物
|
||||
|
||||
= link_to changelog do
|
||||
Version
|
||||
%strong= current_page.metadata[:page][:version]
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
|
||||
.answers
|
||||
%h3#what
|
||||
%a.anchor{ href: "#what", aria_hidden: "true" }
|
||||
更新日誌是什麼？
|
||||
|
||||
%p
|
||||
更新日誌（Changelog）是個記錄專案演進版本間的差異，以時間倒敘、由人工攥寫的列表。
|
||||
|
||||
%h3#why
|
||||
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||||
為什麼需要提供更新日誌？
|
||||
|
||||
%p
|
||||
為了讓使用者和開發人員更簡單明確地了解各個版本之間有著哪些改動。
|
||||
|
||||
%h3#who
|
||||
%a.anchor{ href: "#who", aria_hidden: "true" }
|
||||
哪些人需要更新日誌？
|
||||
|
||||
%p
|
||||
大家都需要更新日誌。無論是使用者還是開發者，軟體最終的用戶都會在意軟體包含了什麼。當軟體更新了，大家會希望知道改了什麼、為什麼要改。
|
||||
|
||||
.good-practices
|
||||
%h3#how
|
||||
%a.anchor{ href: "#how", aria_hidden: "true" }
|
||||
如何寫出高品質的日誌？
|
||||
|
||||
%h4#principles
|
||||
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
||||
指導原則
|
||||
|
||||
%ul
|
||||
%li
|
||||
日誌是寫給「人」看的，不是機器。
|
||||
%li
|
||||
每個版本都應該有獨立的進入點。
|
||||
%li
|
||||
相同類型的改動應分組放置。
|
||||
%li
|
||||
版本與章節應「可連結化」。
|
||||
%li
|
||||
新版本總是寫在前面。
|
||||
%li
|
||||
每個版本都該註記發佈日期。
|
||||
%li
|
||||
版本命名應遵守#{link_to "語意化版本", semver}格式。
|
||||
|
||||
%a.anchor{ href: "#types", aria_hidden: "true" }
|
||||
%h4#types 改動類型
|
||||
|
||||
%ul
|
||||
%li
|
||||
%code Added
|
||||
當增加了新功能。
|
||||
%li
|
||||
%code Changed
|
||||
當更動了既有的功能。
|
||||
%li
|
||||
%code Deprecated
|
||||
當功能將在近期被移除。
|
||||
%li
|
||||
%code Removed
|
||||
當移除了現有的功能。
|
||||
%li
|
||||
%code Fixed
|
||||
當修復了某些錯誤。
|
||||
%li
|
||||
%code Security
|
||||
當增進了安全性漏洞。
|
||||
|
||||
.effort
|
||||
|
||||
%h3#effort
|
||||
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
||||
如何提升維護更新日誌的效率？
|
||||
|
||||
%p
|
||||
在日誌上方使用 <code>Unreleased</code> 區塊記錄即將發佈的更新內容。
|
||||
|
||||
%p 這麼做能夠：
|
||||
|
||||
%ul
|
||||
%li
|
||||
讓大家知道在未來的版本中可能會有哪些改動。
|
||||
%li
|
||||
發佈新版本時，直接將 <code>Unreleased</code> 移到新版本的區塊就完成了 ヾ(*´ω｀*)ノ
|
||||
|
||||
.bad-practices
|
||||
%h3#bad-practices
|
||||
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||||
難道日誌能寫得很糟嗎？
|
||||
|
||||
%p 當然。下面有些糟糕的範例：
|
||||
|
||||
%h4#log-diffs
|
||||
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||||
🚫 直接使用 git log
|
||||
|
||||
%p
|
||||
使用 git log 作為更新日誌絕對不是個好主意：git log 充滿了各種無意義的訊息，像 merge commits
|
||||
、亂七八糟的提交訊息、文件更新等。
|
||||
|
||||
%p
|
||||
Commits 的目的應該是記錄原始碼的演化過程。有些項目會清理 commits，有些卻不會。
|
||||
|
||||
%p
|
||||
更新日誌的目的則是記錄那些值得一提的改動，經常涵蓋多個 commits，最終目的仍是讓使用者一目了然。
|
||||
|
||||
%h4#ignoring-deprecations
|
||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||
🚫 忽略 Deprecations
|
||||
|
||||
%p
|
||||
當使用者升級版本時，他應該要能預先知道哪些環節可能會出問題。理想的情形下，應該讓使用者有空間能預先升級即將被棄用的功能；待替換掉棄用功能之後，再升級至棄用功能被真正移除的版本。
|
||||
|
||||
%p
|
||||
即使不這麼做，也要在更新日誌中列出棄用的、移除的、或是任何可能導致程式碼失效的重大改動。
|
||||
|
||||
%h4#confusing-dates
|
||||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||
🚫 易混淆的日期格式
|
||||
|
||||
%p
|
||||
在世界的每個角落，不同區域有著不同的時間格式，找到讓大家都滿意的日期格式不是件簡單的事。使用像
|
||||
<code>2017-07-17</code> 的格式能清楚傳達日期、不易與其他日期格式混淆，同時也遵守
|
||||
#{link_to "ISO 標準", iso}，因此推薦使用像這樣的日期格式。
|
||||
|
||||
%aside
|
||||
其實還有許多應該避免的。大家可以透過
|
||||
= link_to "Issue", issues
|
||||
或是 Pull Request 協助蒐集 ฅ' ω 'ฅ
|
||||
|
||||
.frequently-asked-questions
|
||||
%h3#frequently-asked-questions
|
||||
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
||||
常見問題
|
||||
|
||||
%h4#standard
|
||||
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
||||
有沒有標準格式可以參考呢？
|
||||
|
||||
%p
|
||||
並沒有。雖然有 #{link_to "GNU 更新日誌指南", gnu_changelog_styleguide} 以及只有兩段長的
|
||||
#{link_to "GNU - The NEWS File 指南", gnu_the_news}（括弧笑），但這些並不足以稱為「標準」。
|
||||
|
||||
%p
|
||||
這項專案的宗旨在於提供一個
|
||||
#{link_to "更好的更新日誌範例", changelog}，源於觀察開源社群中優秀的實際案例，把它們蒐集在一起。
|
||||
|
||||
%p
|
||||
歡迎各位#{link_to "提供", issues}有建設性的建議和批評。
|
||||
|
||||
%h4#filename
|
||||
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
||||
更新日誌的檔案名稱應該是？
|
||||
|
||||
%p
|
||||
通常使用 <code>CHANGELOG.md</code>。也有用
|
||||
<code>HISTORY</code>、<code>NEWS</code>、或是 <code>RELEASES</code> 的例子。
|
||||
|
||||
%p
|
||||
或許你認為取什麼名字並不是件多麼重要的事，但為什麼要讓只是想看日誌的使用者不容易找到它呢？
|
||||
|
||||
%h4#github-releases
|
||||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||||
那麼 GitHub Releases 呢？
|
||||
|
||||
%p
|
||||
這是個好問題。#{link_to "GitHub Releases", ghr}
|
||||
能手動在簡單的 git tag（如
|
||||
<code>v1.0.0</code>） 上附加豐富的版本資訊，也能把附帶的 tag
|
||||
messages 轉換成漂亮的日誌格式。
|
||||
|
||||
%p
|
||||
GitHub Releases 產生的日誌只能在 GitHub 上瀏覽，雖然 GitHub Releases
|
||||
能做出接近本專案範例的日誌格式，但這會增加些許與 GitHub 的相依性。
|
||||
|
||||
%p
|
||||
現行的 GitHub Releases
|
||||
畢竟不像典型的大寫文件（<code>README</code>、<code>CONTRIBUTING</code>
|
||||
之類的），按理說會增加使用者找到的難度。另外還有個小問題，目前 GitHub
|
||||
Releases 頁面上並沒有提供兩版版本之間 commit logs 的連結。
|
||||
|
||||
%h4#automatic
|
||||
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
||||
更新日誌能被自動生成嗎？
|
||||
|
||||
%p
|
||||
非常困難，各式各樣的提交訊息和檔案名稱難以完全掌握。
|
||||
|
||||
%p
|
||||
另外，有些開源專案使用由 #{link_to "Gemnasium", gemnasium}
|
||||
團隊開發的 #{link_to "Vandamme", vandamme}
|
||||
轉換更新日誌，或許可以當作參考。
|
||||
|
||||
%h4#yanked
|
||||
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
||||
那麼被撤下的版本呢？
|
||||
|
||||
%p
|
||||
因為重大漏洞或安全性問題而被撤下（unpublished）的版本通常不會出現在日誌裡，但建議仍然記錄下來。你可以這樣記錄它們：
|
||||
|
||||
%p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
|
||||
|
||||
%p
|
||||
其中 <code>[YANKED]</code> 標記應該和原因顯眼地標示在一起，讓使用者注意到它是最重要的事。此外，用中括弧能讓轉換用的程式更容易辨認它們。
|
||||
|
||||
%h4#rewrite
|
||||
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
||||
可以更改過去版本的日誌內容嗎？
|
||||
|
||||
%p
|
||||
當然可以，總是會有好的原因來改善以往寫下的日誌。我也時常發 pull request
|
||||
給更新日誌不齊全的開源專案。
|
||||
|
||||
%p
|
||||
偶爾會發現自己遺漏了某項重大更新的紀錄，很明顯你應該補齊它們。
|
||||
|
||||
%h4#contribute
|
||||
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
||||
我能做些什麼嗎？
|
||||
|
||||
%p
|
||||
這份文件並不是《真理》，而是我經過深思熟慮、遵循蒐集到的資訊和範例之後提出的建議。
|
||||
|
||||
%p
|
||||
源於我期望社群能達到共識，我相信討論的過程與結果一樣重要。
|
||||
|
||||
%p
|
||||
所以，<strong>#{link_to "加入我們", gh}</strong>吧 ٩(｡・ω・｡)و
|
||||
|
||||
.press
|
||||
%h3 訪談
|
||||
%p
|
||||
我在 #{link_to "The Changelog podcast", thechangelog} 上講述了為什麼維護者與協作者應該在意更新日誌，以及建立這項專案背後的契機。
|
||||
Loading…
x
Reference in New Issue
Block a user