mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-29 16:54:12 +02:00
Olivier Lacan
GitHub
commit
6c3101d886
46
CHANGELOG.md
46
CHANGELOG.md
@ -6,18 +6,41 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
|
||||
|
||||
## [Unreleased]
|
||||
### Added
|
||||
- zh-CN and zh-TW translations from @tianshuo.
|
||||
- de translation from @mpbzh.
|
||||
- it-IT translation from @roalz.
|
||||
- sv translation from @magol.
|
||||
- tr-TR translation from @karalamalar.
|
||||
- fr translation from @zapashcanon.
|
||||
- "Why keep a changelog?" section.
|
||||
- "Who needs a changelog?" section.
|
||||
- "How do I make a changelog?" section.
|
||||
- "Frequently Asked Questions" section.
|
||||
- New "Guiding Principles" sub-section to "How do I make a changelog?".
|
||||
- Simplified and Traditional Chinese translations from @tianshuo.
|
||||
- German translation from @mpbzh.
|
||||
- Italian translation from @roalz.
|
||||
- Swedish translation from @magol.
|
||||
- Turkish translation from @karalamalar.
|
||||
- French translation from @zapashcanon.
|
||||
- Brazilian Portugese translation from @aisamu.
|
||||
- Polish translation from @amielucha.
|
||||
|
||||
### Changed
|
||||
- Start using "changelog" over "change log" since it's the common usage.
|
||||
- Start versioning based on the current English version at 0.3.0 to help
|
||||
translation authors keep things up-to-date.
|
||||
- Fix typos in zh-CN translation.
|
||||
- Fix typos in pt-BR translation.
|
||||
- Rewrite "What makes unicorns cry?" section.
|
||||
- Rewrite "Ignoring Deprecations" sub-section to clarify the ideal
|
||||
scenario.
|
||||
- Improve "Commit log diffs" sub-section to further argument against
|
||||
them.
|
||||
- Merge "Why can’t people just use a git log diff?" with "Commit log
|
||||
diffs"
|
||||
- Fix typos in Simplified Chinese and Traditional Chinese translations.
|
||||
- Fix typos in Brazilian Portugese translation.
|
||||
- Fix typos in Turkish translation.
|
||||
- Fix typos in Czech translation.
|
||||
- Fix typos in Swedish translation.
|
||||
- Improve phrasing in French translation.
|
||||
- Fix phrasing and spelling in German translation.
|
||||
|
||||
### Removed
|
||||
- Section about "changelog" vs "CHANGELOG".
|
||||
|
||||
## [0.3.0] - 2015-12-03
|
||||
### Added
|
||||
@ -27,8 +50,8 @@ translation authors keep things up-to-date.
|
||||
|
||||
## [0.2.0] - 2015-10-06
|
||||
### Changed
|
||||
- Remove exclusionary mentions of "open source" since this project can benefit
|
||||
both "open" and "closed" source projects equally.
|
||||
- Remove exclusionary mentions of "open source" since this project can
|
||||
benefit both "open" and "closed" source projects equally.
|
||||
|
||||
## [0.1.0] - 2015-10-06
|
||||
### Added
|
||||
@ -94,7 +117,8 @@ notable changes.
|
||||
|
||||
## 0.0.1 - 2014-05-31
|
||||
### Added
|
||||
- This CHANGELOG file to hopefully serve as an evolving example of a standardized open source project CHANGELOG.
|
||||
- This CHANGELOG file to hopefully serve as an evolving example of a
|
||||
standardized open source project CHANGELOG.
|
||||
- CNAME file to enable GitHub Pages custom domain
|
||||
- README now contains answers to common questions about CHANGELOGs
|
||||
- Good examples and basic guidelines, including proper date formatting.
|
||||
|
||||
@ -117,7 +117,7 @@ GEM
|
||||
rb-fsevent (0.9.7)
|
||||
rb-inotify (0.9.7)
|
||||
ffi (>= 0.5.0)
|
||||
redcarpet (3.3.3)
|
||||
redcarpet (3.4.0)
|
||||
rouge (2.0.5)
|
||||
sass (3.4.22)
|
||||
servolux (0.12.0)
|
||||
@ -146,4 +146,4 @@ DEPENDENCIES
|
||||
redcarpet
|
||||
|
||||
BUNDLED WITH
|
||||
1.12.0
|
||||
1.13.6
|
||||
|
||||
146
config.rb
146
config.rb
@ -3,21 +3,84 @@
|
||||
# --------------------------------------
|
||||
|
||||
# ----- Site ----- #
|
||||
$last_version = "0.3.0"
|
||||
# Last version should be the latest English version since the manifesto is first
|
||||
# written in English, then translated into other languages later.
|
||||
$last_version = (Dir.entries("source/en") - %w[. ..]).last
|
||||
|
||||
# This list of languages populates the language navigation.
|
||||
issues_url = 'https://github.com/olivierlacan/keep-a-changelog/issues'
|
||||
$languages = {
|
||||
"cs" => "Čeština",
|
||||
"de" => "Deutsch",
|
||||
"en" => "English",
|
||||
"es-ES" => "Español",
|
||||
"fr" => "Français",
|
||||
"it-IT" => "Italiano",
|
||||
"pt-BR" => "Brazilian Portugese",
|
||||
"ru" => "Pyccкий",
|
||||
"sl" => "Slovenščina",
|
||||
"sv" => "Svenska",
|
||||
"tr-TR" => "Türkçe",
|
||||
"zh-CN" => "简体中文",
|
||||
"zh-TW" => " 繁體中文"
|
||||
"cs" => {
|
||||
name: "Čeština",
|
||||
notice: ""
|
||||
},
|
||||
"de" => {
|
||||
name: "Deutsch",
|
||||
notice: "Die neuste version (#{$last_version}) ist noch nicht auf Deutsch
|
||||
verfügbar, aber du kannst sie dir <a href='/en/'>auf Englisch durchlesen</a>
|
||||
und <a href='#{issues_url}'>bei der Übersetzung mithelfen</a>."
|
||||
},
|
||||
"en" => {
|
||||
default: true,
|
||||
name: "English",
|
||||
notice: ""
|
||||
},
|
||||
"es-ES" => {
|
||||
name: "Español",
|
||||
notice: "Aún no está disponible la última versión (#{$last_version}) en
|
||||
español, pero por ahora puedes <a href='/en/'>leerla en inglés</a> y <a
|
||||
href='#{issues_url}'>ayudar a traducirla</a>."
|
||||
},
|
||||
"fr" => {
|
||||
name: "Français",
|
||||
notice: "La dernière version (#{$last_version}) n'est pas encore disponible
|
||||
en français, mais vous pouvez la <a href='/en/'>lire en anglais</a> pour
|
||||
l'instant et <a href='#{issues_url}'>aider à la traduire</a>."
|
||||
},
|
||||
"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",
|
||||
notice: ""
|
||||
},
|
||||
"pt-BR" => {
|
||||
name: "Brazilian Portugese",
|
||||
notice: "A última versão (#{$last_version}) ainda não está disponível em
|
||||
Português mas nesse momento você pode <a href='/en/'>lê-la em inglês</a> e
|
||||
<a href='#{issues_url}'>ajudar em sua tradução</a>."
|
||||
},
|
||||
"ru" => {
|
||||
name: "Pyccкий",
|
||||
notice: "Самая последняя версия (#{$last_version}) ещё пока не переведена на
|
||||
русский, но вы можете <a href='/en/'>прочитать её на английском</a> и <a
|
||||
href='#{issues_url}'>помочь с переводом</a>."
|
||||
},
|
||||
"sl" => {
|
||||
name: "Slovenščina",
|
||||
notice: ""
|
||||
},
|
||||
"sv" => {
|
||||
name: "Svenska",
|
||||
notice: "Den senaste versionen (#{$last_version}) är ännu inte tillgänglig på Svenska,
|
||||
men du kan <a href='/en/'>läsa det på engelska</a> och även <a
|
||||
href='#{issues_url}'>hjälpa till att översätta det</a>."
|
||||
},
|
||||
"tr-TR" => {
|
||||
name: "Türkçe",
|
||||
notice: ""
|
||||
},
|
||||
"zh-CN" => {
|
||||
name: "简体中文",
|
||||
notice: ""
|
||||
},
|
||||
"zh-TW" => {
|
||||
name: "繁體中文",
|
||||
notice: ""
|
||||
}
|
||||
}
|
||||
|
||||
activate :i18n,
|
||||
@ -31,8 +94,9 @@ set :site_url, 'http://keepachangelog.com'
|
||||
redirect "index.html", to: "en/#{$last_version}/index.html"
|
||||
|
||||
$languages.each do |language|
|
||||
language_param = language.last.parameterize
|
||||
redirect "#{language.first}/index.html", to: "#{language.first}/#{$last_version}/index.html"
|
||||
code = language.first
|
||||
versions = Dir.entries("source/#{code}") - %w[. ..]
|
||||
redirect "#{code}/index.html", to: "#{code}/#{versions.last}/index.html"
|
||||
end
|
||||
|
||||
# ----- Assets ----- #
|
||||
@ -50,12 +114,38 @@ activate :automatic_image_sizes
|
||||
|
||||
activate :syntax
|
||||
set :markdown_engine, :redcarpet
|
||||
set :markdown, {
|
||||
|
||||
## Override default Redcarpet renderer in order to define a class
|
||||
class CustomMarkdownRenderer < Redcarpet::Render::HTML
|
||||
def doc_header
|
||||
%Q[<nav role="navigation" class="toc">#{@header}</nav>]
|
||||
end
|
||||
|
||||
def header(text, header_level)
|
||||
slug = text.parameterize
|
||||
tag_name = "h#{header_level}"
|
||||
anchor_link = "<a id='#{slug}' class='anchor' href='##{slug}' aria-hidden='true'></a>"
|
||||
header_tag_open = "<#{tag_name} id='#{slug}'>"
|
||||
|
||||
output = ""
|
||||
output << header_tag_open
|
||||
output << anchor_link
|
||||
output << text
|
||||
output << "</#{tag_name}>"
|
||||
|
||||
output
|
||||
end
|
||||
end
|
||||
|
||||
$markdown_config = {
|
||||
fenced_code_blocks: true,
|
||||
footnotes: true,
|
||||
smartypants: true,
|
||||
tables: true
|
||||
tables: true,
|
||||
with_toc_data: true,
|
||||
renderer: CustomMarkdownRenderer
|
||||
}
|
||||
set :markdown, $markdown_config
|
||||
|
||||
# --------------------------------------
|
||||
# Helpers
|
||||
@ -112,3 +202,23 @@ activate :autoprefixer do |config|
|
||||
config.browsers = ['last 2 versions', 'Explorer >= 10']
|
||||
config.cascade = false
|
||||
end
|
||||
|
||||
# Haml doesn't pick up on Markdown configuration so we have to remove the
|
||||
# default Markdown Haml filter and reconfigure one that follows our
|
||||
# global configuration.
|
||||
|
||||
module Haml::Filters
|
||||
remove_filter("Markdown") #remove the existing Markdown filter
|
||||
|
||||
module Markdown
|
||||
include Haml::Filters::Base
|
||||
|
||||
def renderer
|
||||
$markdown_config[:renderer]
|
||||
end
|
||||
|
||||
def render(text)
|
||||
Redcarpet::Markdown.new(renderer.new($markdown_config)).render(text)
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
BIN
source/assets/images/bg-hero@2x.png
Normal file
BIN
source/assets/images/bg-hero@2x.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 161 KiB |
BIN
source/assets/images/bg-img1@2x.png
Normal file
BIN
source/assets/images/bg-img1@2x.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 37 KiB |
BIN
source/assets/images/bg-img2@2x.png
Normal file
BIN
source/assets/images/bg-img2@2x.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
1
source/assets/images/keep-a-changelog-mark.svg
Normal file
1
source/assets/images/keep-a-changelog-mark.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 187.05 184.89"><defs><style>.cls-1{fill:#f4e0c2;}</style></defs><title>Artboard 1 copy 3</title><path class="cls-1" d="M62.09,6.5c-15.39,3.08-27.7,10.71-36.6,22.67C14.11,44.48,7.71,63.39,5.36,88.69c-.92,10,.06,20.05,1.34,31.18a73.74,73.74,0,0,0,15.86,38.56c6.9,8.56,14.82,14.18,24.2,17.19a88.55,88.55,0,0,0,24.67,4.25,45.42,45.42,0,0,0,5.88-.25l3.08-.31c4.24-.43,8.49-.86,12.73-1.37a158.36,158.36,0,0,0,54.68-16.7c14.84-7.75,25.22-19.18,30.84-34,2.62-6.88,3.87-12.67,3.87-18.08a33.91,33.91,0,0,0-.47-5.64c-3-17.59-9.14-32.75-18.9-46.33-12.09-16.83-24.32-28.68-38.48-37.31C103.11,6.76,82.64,2.38,62.09,6.5Zm29.73,8.13c20.19,4.42,38,14.81,52.92,30.87,16.92,18.2,26.56,37.31,29.49,58.42.53,3.91-.09,8.24-.71,12-2.87,17.21-12.3,30.05-28,38.16a155.31,155.31,0,0,1-53,16.14c-4.13.49-8.28.91-13,1.39l-.65.07a50.59,50.59,0,0,1-12.26-.23h0c-5.11-.72-10.89-1.55-16.45-2.87-13.07-3.11-22.7-12-29.42-27.06-5.06-11.37-7.68-24-8-38.7a132.53,132.53,0,0,1,8.5-50.28C25.83,40.4,32.46,27,46.85,19.86,61,12.82,75.74,11.11,91.83,14.63Z"/><path class="cls-1" d="M39.83,44.82C28.74,60.48,23,78.7,22.74,99a74.87,74.87,0,0,0,5.94,32.45c8,19,22.58,30.06,42.21,32,20.68,2,41-2.82,60.49-14.33a60.07,60.07,0,0,0,20.5-19.41,52.54,52.54,0,0,0,8.64-28.54c0-16-7.51-33.07-22.55-50.76a47.36,47.36,0,0,0-5.21-5.23c-23-19.78-44.72-25.81-66.87-18.4C54.05,30.67,45.78,36.43,39.83,44.82ZM148.43,121a50.36,50.36,0,0,1-21.5,22.1c-16.67,9.11-31.92,13.14-47.77,12.67H79c-11.47.45-21.38-2.36-30.31-8.6-5.18-3.61-9.18-8.89-12.24-16.15A80.91,80.91,0,0,1,30,99.42a93.56,93.56,0,0,1,7.57-35.9,89.91,89.91,0,0,1,6.47-12l1.2-2C50.2,41.33,58,37.4,68.19,34c16-5.27,31.72-2.55,49.55,8.56C130.93,50.82,141.12,63,148,78.87,154.56,93.81,154.69,108,148.43,121Z"/><path class="cls-1" d="M104.8,48c-17.06-7.52-32.45-5.88-45.72,4.88C48.76,61.24,42.58,73,39.63,89.81a53.56,53.56,0,0,0,5,34.12c7.85,15.19,20.7,23,37.17,22.56h.06c21.88-1.15,37.79-9.24,48.62-24.76a41.46,41.46,0,0,0,7.84-24,43,43,0,0,0-1.79-12.12C131.2,67.6,120.54,54.95,104.8,48ZM81.6,138.55h-.29c-7.43.59-14.75-1.67-21.77-6.73A27.13,27.13,0,0,1,50,119.1a56.51,56.51,0,0,1-3.8-20.17,62.68,62.68,0,0,1,5.52-25c5-11.51,12.75-18.51,23.78-21.4,9.07-2.36,18.1-1.45,27.59,2.8,13.78,6.16,22.73,17.25,26.62,33s-2,31.1-15.28,40.11C103.49,135.83,92.75,139.14,81.6,138.55Z"/><path class="cls-1" d="M83.47,105.25v14.12H74.93V68.46h8.54V96.28l9.11-9.89h11.16L89.9,100.87l16.81,18.5H95.9Z"/></svg>
|
||||
|
After Width: | Height: | Size: 2.4 KiB |
@ -1 +1,32 @@
|
||||
//= require_tree .
|
||||
document.addEventListener("DOMContentLoaded", function(){
|
||||
var select = document.querySelector('.locales select');
|
||||
select.addEventListener('change', function(event){
|
||||
origin = window.location.origin;
|
||||
languageCode = event.currentTarget.selectedOptions[0].value
|
||||
window.location.replace(origin + "/" + languageCode)
|
||||
});
|
||||
|
||||
var faqHeaders = document.querySelectorAll('.frequently-asked-questions h4');
|
||||
|
||||
for(header of faqHeaders){
|
||||
header.addEventListener('click', toggleVisibility);
|
||||
}
|
||||
|
||||
function toggleVisibility(event) {
|
||||
element = event.target;
|
||||
element.classList.toggle('is-visible')
|
||||
|
||||
lastParagraph = element.nextElementSibling;
|
||||
paragraphs = [];
|
||||
paragraphs.push(lastParagraph);
|
||||
|
||||
while (lastParagraph.nextElementSibling.tagName == "P") {
|
||||
lastParagraph = lastParagraph.nextElementSibling;
|
||||
paragraphs.push(lastParagraph)
|
||||
}
|
||||
|
||||
for(paragraph of paragraphs) {
|
||||
paragraph.classList.toggle('is-visible');
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
17
source/assets/stylesheets/anchors.sass
Normal file
17
source/assets/stylesheets/anchors.sass
Normal file
@ -0,0 +1,17 @@
|
||||
.anchor
|
||||
display: none
|
||||
font-style: normal
|
||||
font-weight: normal
|
||||
position: absolute
|
||||
right: 100%
|
||||
top: 0
|
||||
|
||||
.anchor::before
|
||||
line-height: 3.2
|
||||
content: "∞"
|
||||
color: $color-ocre
|
||||
padding-right: 0.1em
|
||||
|
||||
.anchor:hover
|
||||
a
|
||||
text-decoration: none
|
||||
@ -1,123 +1,97 @@
|
||||
$base-font-family: "Carrois Gothic", "Helvetica Neue", Helvetica, Arial, sans-serif
|
||||
$base-font-family: 'Muli', "Helvetica Neue", Helvetica, Arial, sans-serif
|
||||
$source-code-font-family: "Source Code Pro", monospace
|
||||
|
||||
$color-black: #342828
|
||||
$color-white: #FFFFFF
|
||||
$color-ocre: #E05735
|
||||
$color-gold: #faa930
|
||||
$color-bark: #3F2B2D
|
||||
$color-sand: #FEECD3
|
||||
$color-light-sand: lighten($color-sand, 10%)
|
||||
|
||||
@import "layout"
|
||||
@import "anchors"
|
||||
@import "sections"
|
||||
|
||||
html
|
||||
font: 14px/1.4 $base-font-family
|
||||
color: #333
|
||||
font: 16px/1.4 $base-font-family
|
||||
color: #342828
|
||||
background-color: $color-sand
|
||||
|
||||
a
|
||||
color: #E10FCE
|
||||
font-weight: bold
|
||||
color: $color-ocre
|
||||
text-decoration: none
|
||||
|
||||
a:hover
|
||||
text-decoration: underline
|
||||
|
||||
h1
|
||||
color: #C647BF
|
||||
font-size: 4.1em
|
||||
color: $color-ocre
|
||||
font-size: 3.2em
|
||||
font-weight: bold
|
||||
font-family: $source-code-font-family
|
||||
font-family: $base-font-family
|
||||
margin-bottom: 0
|
||||
line-height: 1
|
||||
word-spacing: -0.3em
|
||||
text-transform: lowercase
|
||||
width: 50%
|
||||
|
||||
h2
|
||||
margin-top: 0
|
||||
font-size: 1.2em
|
||||
margin-top: 0.2em
|
||||
margin-bottom: 2em
|
||||
|
||||
h1, h2
|
||||
text-align: center
|
||||
text-align: left
|
||||
|
||||
h3
|
||||
font-size: 1.3em
|
||||
font-family: $source-code-font-family
|
||||
margin-bottom: 0
|
||||
font-family: $base-font-family
|
||||
margin-bottom: 1em
|
||||
position: relative
|
||||
padding-left: .1em
|
||||
|
||||
h3:hover .anchor, h3:focus .anchor
|
||||
display: block
|
||||
|
||||
.anchor
|
||||
display: none
|
||||
font-style: normal
|
||||
font-weight: normal
|
||||
position: absolute
|
||||
right: 100%
|
||||
top: 0
|
||||
|
||||
.anchor::before
|
||||
content: '¶'
|
||||
|
||||
.anchor:hover
|
||||
text-decoration: none
|
||||
|
||||
h3 ~ p
|
||||
margin-top: 0
|
||||
|
||||
article
|
||||
margin: 0 auto
|
||||
width: 640px
|
||||
|
||||
article p
|
||||
font-size: 1.3em
|
||||
|
||||
article code
|
||||
border-radius: 0.315em
|
||||
border: 1px solid #ccc
|
||||
padding: 0 0.3em 0.040em
|
||||
font-size: 0.9em
|
||||
|
||||
article img
|
||||
margin: 0 auto
|
||||
max-width: 100%
|
||||
text-align: center
|
||||
display: block
|
||||
box-shadow: rgba(0, 0, 0, 0.37) 0px 0px 6px
|
||||
border-radius: 7px
|
||||
padding: 0.4em 0.9em
|
||||
|
||||
article > ul
|
||||
font-size: 1.2em
|
||||
padding-left: 0
|
||||
|
||||
article > ul ul
|
||||
padding-left: 1em
|
||||
|
||||
article ul
|
||||
line-height: 1.5
|
||||
list-style-position: inside
|
||||
list-style-type: square
|
||||
|
||||
footer
|
||||
font-size: .7em
|
||||
border-top: 1px solid #e9e6e1
|
||||
margin-top: 1em
|
||||
margin-bottom: 2em
|
||||
h1, h2, h3
|
||||
margin-top: 0
|
||||
padding-top: 1em
|
||||
|
||||
.license
|
||||
float: left
|
||||
.about
|
||||
text-align: center
|
||||
|
||||
.about
|
||||
float: right
|
||||
|
||||
.about, .license
|
||||
margin-top: 0
|
||||
|
||||
.changelog
|
||||
border: 1px solid #aaa
|
||||
margin: 0 0.5em
|
||||
padding: 1em
|
||||
overflow-x: auto
|
||||
height: 20em
|
||||
header
|
||||
.locales, .mark
|
||||
margin-bottom: -2em
|
||||
margin-top: 2em
|
||||
margin-right: 2em
|
||||
|
||||
.mark
|
||||
margin-left: 3em
|
||||
float: left
|
||||
|
||||
.footer
|
||||
line-height: 2.2
|
||||
|
||||
.mark
|
||||
float: left
|
||||
|
||||
.locales
|
||||
float: right
|
||||
|
||||
.locales li
|
||||
float: right
|
||||
font-size: 0.7em
|
||||
display: inline
|
||||
list-style-type: none
|
||||
padding-right: 20px
|
||||
white-space: nowrap
|
||||
|
||||
pre, code
|
||||
background-color: $color-light-sand
|
||||
font-family: $source-code-font-family
|
||||
|
||||
43
source/assets/stylesheets/layout.sass
Normal file
43
source/assets/stylesheets/layout.sass
Normal file
@ -0,0 +1,43 @@
|
||||
$break-small: em(480px)
|
||||
$break-medium: em(800px)
|
||||
$break-large: em(1024px)
|
||||
|
||||
article
|
||||
margin: 0 auto
|
||||
width: 65em
|
||||
|
||||
.main
|
||||
background-color: $color-white
|
||||
margin-bottom: 2em
|
||||
|
||||
div
|
||||
padding-left: 20%
|
||||
padding-right: 20%
|
||||
padding-bottom: 3em
|
||||
|
||||
aside
|
||||
background-color: lighten(desaturate($color-bark, 5%), 10%)
|
||||
margin-bottom: -3em
|
||||
margin-left: -35%
|
||||
margin-right: -35%
|
||||
margin-top: 3em
|
||||
padding: 2em 20%
|
||||
text-align: center
|
||||
|
||||
aside &
|
||||
background-position: top
|
||||
|
||||
article p
|
||||
font-size: 1.3em
|
||||
|
||||
article code
|
||||
border-radius: 0.315em
|
||||
border: 1px solid #ccc
|
||||
padding: 0 0.3em 0.040em
|
||||
font-size: 0.9em
|
||||
|
||||
article ul
|
||||
font-size: 1.1em
|
||||
line-height: 1.5
|
||||
list-style-type: square
|
||||
padding-left: 1em
|
||||
180
source/assets/stylesheets/sections.sass
Normal file
180
source/assets/stylesheets/sections.sass
Normal file
@ -0,0 +1,180 @@
|
||||
div.header
|
||||
padding-top: 5em
|
||||
padding-bottom: 0.1em
|
||||
background-color: $color-ocre
|
||||
background-image: image-url("bg-hero@2x.png")
|
||||
background-size: 100%
|
||||
|
||||
h1
|
||||
color: $color-sand
|
||||
|
||||
h2
|
||||
font-weight: normal
|
||||
|
||||
a
|
||||
color: $color-black
|
||||
|
||||
.title
|
||||
width: 80%
|
||||
margin: 0 auto
|
||||
margin-bottom: -2em
|
||||
|
||||
.changelog
|
||||
background-color: $color-white
|
||||
box-shadow: 0px 4px 12px 0px hsla(0, 0%, 0%, 0.2)
|
||||
font-size: 0.8em
|
||||
height: 20em
|
||||
margin-bottom: -14em
|
||||
margin-left: 0.5em
|
||||
margin-right: 0.5em
|
||||
margin-top: 1em
|
||||
overflow-x: auto
|
||||
padding: 1em
|
||||
|
||||
div.answers
|
||||
margin-top: 12em
|
||||
padding-left: 25%
|
||||
padding-right: 25%
|
||||
background-color: $color-white
|
||||
|
||||
h3
|
||||
font-size: 1.7em
|
||||
color: $color-ocre
|
||||
|
||||
a
|
||||
color: $color-gold
|
||||
|
||||
p
|
||||
font-size: 1em
|
||||
|
||||
.good-practices
|
||||
background-color: $color-gold
|
||||
background-image: image-url("bg-img1@2x.png")
|
||||
background-position: bottom left
|
||||
background-repeat: no-repeat
|
||||
background-size: 100%
|
||||
padding-top: 2em
|
||||
|
||||
a.anchor
|
||||
color: $color-black
|
||||
|
||||
h3
|
||||
font-size: 1.6em
|
||||
font-weight: bold
|
||||
width: 50%
|
||||
|
||||
h4
|
||||
padding-left: 15em
|
||||
|
||||
ul
|
||||
font-size: 1em
|
||||
padding-left: 16em
|
||||
|
||||
p
|
||||
a
|
||||
color: $color-white
|
||||
text-decoration: underline
|
||||
|
||||
div.bad-practices
|
||||
color: $color-white
|
||||
background-color: $color-bark
|
||||
background-image: image-url("bg-img2@2x.png")
|
||||
background-position: bottom left
|
||||
background-repeat: no-repeat
|
||||
background-size: 100%
|
||||
padding-top: 3em
|
||||
|
||||
code
|
||||
color: $color-black
|
||||
background-color: desaturate(lighten($color-bark, 50%), 10%)
|
||||
border: none
|
||||
|
||||
p, aside
|
||||
a
|
||||
color: $color-gold
|
||||
text-decoration: underline
|
||||
|
||||
aside
|
||||
a
|
||||
text-decoration: none
|
||||
|
||||
h3
|
||||
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%
|
||||
background-color: $color-white
|
||||
|
||||
h3
|
||||
font-size: 1.6em
|
||||
font-weight: bold
|
||||
color: $color-ocre
|
||||
|
||||
div.frequently-asked-questions
|
||||
padding-top: 2em
|
||||
padding-left: 25%
|
||||
padding-right: 25%
|
||||
background-color: $color-white
|
||||
|
||||
h2
|
||||
color: $color-ocre
|
||||
|
||||
h3
|
||||
color: $color-ocre
|
||||
margin-bottom: 1.5em
|
||||
font-size: 1.7em
|
||||
|
||||
h4
|
||||
cursor: pointer
|
||||
border-bottom: 1px solid transparentize($color-bark, 0.8)
|
||||
padding: 0 1.1em 1.3em 0
|
||||
|
||||
&:after
|
||||
content: "⌄"
|
||||
text-align: right
|
||||
float: right
|
||||
font-size: 2.8em
|
||||
line-height: 0.4
|
||||
margin-right: -0.3em
|
||||
|
||||
|
||||
&.is-visible:after
|
||||
content: "-"
|
||||
|
||||
h4 ~ p
|
||||
display: none
|
||||
font-size: 0.9em
|
||||
|
||||
h4 ~ p.is-visible
|
||||
display: inherit
|
||||
|
||||
.footer
|
||||
font-size: .6em
|
||||
font-weight: normal
|
||||
border-top: 1px solid #e9e6e1
|
||||
padding-top: 1em
|
||||
padding-left: 2em
|
||||
padding-right: 2em
|
||||
|
||||
background-color: $color-ocre
|
||||
color: $color-sand
|
||||
|
||||
a
|
||||
color: $color-white
|
||||
text-decoration: underline
|
||||
|
||||
&:after
|
||||
content: ""
|
||||
display: table
|
||||
clear: both
|
||||
29
source/assets/stylesheets/table-of-contents.sass
Normal file
29
source/assets/stylesheets/table-of-contents.sass
Normal file
@ -0,0 +1,29 @@
|
||||
.toc
|
||||
position: fixed
|
||||
z-index: 9999
|
||||
top: 10%
|
||||
left: 0
|
||||
|
||||
ul
|
||||
list-style-position: inside
|
||||
list-style-type: decimal-leading-zero
|
||||
padding: 0 0 0 1em
|
||||
li
|
||||
padding-left: 1em
|
||||
line-height: 2
|
||||
a
|
||||
padding: 0 1em
|
||||
line-height: 2
|
||||
display: none
|
||||
|
||||
span
|
||||
display: none
|
||||
|
||||
li:hover
|
||||
color: $color-sand
|
||||
background: $color-black
|
||||
li:hover a
|
||||
color: $color-sand
|
||||
font-weight: bold
|
||||
background-color: $color-black
|
||||
display: inline-block
|
||||
@ -13,26 +13,25 @@ version: 0.3.0
|
||||
Version **#{current_page.metadata[:page][:version]}**
|
||||
|
||||
### Co je to changelog?
|
||||
Changelog je soubor, který obsahuje organizovaný, chronologicky seřazený
|
||||
seznam podstatných změn pro každou verzi daného projektu.
|
||||
Changelog je soubor, který obsahuje organizovaný, chronologicky seřazený
|
||||
seznam podstatných změn pro každou verzi daného projektu.
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||
|
||||
:markdown
|
||||
### Co je smyslem changelogu?
|
||||
Usnadnit uživatelům a přispěvatelům přesné zobrazení podstatných změn, které
|
||||
byly provedeny mezi jednotlivými vydáními (verzemi) daného projektu.
|
||||
Usnadnit uživatelům a přispěvatelům přesné zobrazení podstatných změn, které
|
||||
byly provedeny mezi jednotlivými vydáními (verzemi) daného projektu.
|
||||
|
||||
### Proč by mi na tom mělo záležet?
|
||||
Protože softwarové nástroje jsou pro lidi. Pokud ti na tom nezáleží, tak proč
|
||||
přispíváš do open source projektů? Určitě musí být v tvém úžasném malém mozku
|
||||
přispíváš do open source projektů? Určitě musí být v tvém úžasném malém mozku
|
||||
alespoň jádro (haha!) ochoty.
|
||||
|
||||
|
||||
[Bavil jsem se s Adamem Stacoviakem a Jerodem Santem na podcastu The Changelog][thechangelog]
|
||||
(název sedí, co?) o tom proč by na tom mělo vedoucím a přispěvatelům projektů
|
||||
záležet a o tom jaká motivace je za tímto projektem. Jestli máš chvilku času
|
||||
(1:06), stojí to za poslech.
|
||||
|
||||
(název sedí, co?) o tom proč by na tom mělo vedoucím a přispěvatelům projektů
|
||||
záležet a o tom jaká motivace je za tímto projektem. Jestli máš chvilku času
|
||||
(1:06), stojí to za poslech.
|
||||
|
||||
### Co dělá changelog dobrým?
|
||||
Výborná otázka, díky za ni.
|
||||
|
||||
@ -52,12 +51,12 @@ version: 0.3.0
|
||||
- `Deprecated` pro dříve stabilní funkce, které budou odstraněny v novějších vydáních a nejsou podporovány.
|
||||
- `Removed` pro funkce odstraněné v daném vydání.
|
||||
- `Fixed` pro opravené chyby.
|
||||
- `Security` pro navržení aktualizace uživatelům v případě bezpečnostních problémů.
|
||||
|
||||
- `Security` pro navržení aktualizace uživatelům v případě bezpečnostních problémů.
|
||||
|
||||
|
||||
### Jak mohu vyžadovanou snahu snížit na minimum?
|
||||
Vždycky měj nahoře sekci `"Unreleased"`, ve které budou schromažďovány všechny
|
||||
změny.
|
||||
Vždycky měj nahoře sekci `"Unreleased"`, ve které budou schromažďovány všechny
|
||||
změny.
|
||||
|
||||
To plní hned dva účely:
|
||||
|
||||
@ -66,103 +65,103 @@ version: 0.3.0
|
||||
|
||||
### Co zaručeně rozbrečí jednorožce?
|
||||
Dobrá… Tak si to povíme.
|
||||
|
||||
|
||||
- **Zkopírování diffu commit logů.** To prostě nedělej, nikomu to nepomůže.
|
||||
- **Nezdůraznění dále nepodporovaných funcí.** Když lidé aktualizují na novou verzi, mělo by jim být bolestivě jasné, že se něco rozbije.
|
||||
- **Data v regionálních formátech.** V USA píšou lidé nejdříve měsíc ("06-02-2012" pro 2. června 2012, což nedává *vůbec žádný* smysl), zatímco mnoho lidí ve zbytku světa píše roboticky vypadající verzi "2 June 2012", ale vyslovují to jinak. "2012-06-02" je logicky napsané od největšího po nejmenší celek, nepřekrývá se nesrozumitelně s jinými fomáty data a je to [ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Proto je to doporučovaný formát dat pro changelogy.
|
||||
|
||||
To ale není všechno. Pomoz mi sbírat jednorožčí slzy tím že
|
||||
- **Data v regionálních formátech.** V USA píšou lidé nejdříve měsíc ("06-02-2012" pro 2. června 2012, což nedává *vůbec žádný* smysl), zatímco mnoho lidí ve zbytku světa píše roboticky vypadající verzi "2 June 2012", ale vyslovují to jinak. "2012-06-02" je logicky napsané od největšího po nejmenší celek, nepřekrývá se nesrozumitelně s jinými fomáty data a je to [ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Proto je to doporučovaný formát dat pro changelogy.
|
||||
|
||||
To ale není všechno. Pomoz mi sbírat jednorožčí slzy tím že
|
||||
[otevřeš issue][issues] nebo pull request.
|
||||
|
||||
|
||||
### Existuje pro formát changelogů nějaký standard?
|
||||
Bohužel ne. Klid. Vím, že se zuřivě snažíš najít ten odkaz na GNU návod jakým
|
||||
stylem psát changelog, nebo onen dvouodstavcový GNU NEWS soubor, který si říká
|
||||
Bohužel ne. Klid. Vím, že se zuřivě snažíš najít ten odkaz na GNU návod jakým
|
||||
stylem psát changelog, nebo onen dvouodstavcový GNU NEWS soubor, který si říká
|
||||
"směrnice". Zmíněný GNU návod je sice hezký začátek, ale je smutně naivní. Být
|
||||
naivní není nic špatného, ale když lidé potřebují radu, málokdy to někomu
|
||||
naivní není nic špatného, ale když lidé potřebují radu, málokdy to někomu
|
||||
pomůže. Obzvlášť, když existuje tolik situací a okrajových případů, se kterými
|
||||
se musí člověk nějak poprat.
|
||||
|
||||
Tento projekt
|
||||
se musí člověk nějak poprat.
|
||||
|
||||
Tento projekt
|
||||
[obsahuje něco, co se doufám jednou stane lepší konvencí pro CHANGELOGy][CHANGELOG].
|
||||
Nemyslím si, že je momentální stav dostatečně dobrý, a jsem toho názoru, že
|
||||
jsme jako komunita schopni vymyslet lepší konvence, pokud se budeme snažit
|
||||
vybrat ty nejlepší praktiky z doopravdových softwarových projektů.
|
||||
Porozhlédněte se a mějte na paměti, že
|
||||
Nemyslím si, že je momentální stav dostatečně dobrý, a jsem toho názoru, že
|
||||
jsme jako komunita schopni vymyslet lepší konvence, pokud se budeme snažit
|
||||
vybrat ty nejlepší praktiky z doopravdových softwarových projektů.
|
||||
Porozhlédněte se a mějte na paměti, že
|
||||
[diskuse a návrhy na zlepšení jsou vítány][issues]!
|
||||
|
||||
|
||||
### Jak by se měl changelog jmenovat?
|
||||
Inu, pokud jste to už nepoznali z příkladu výše, `CHANGELOG.md` je zatím ta
|
||||
nejlepší konvence.
|
||||
|
||||
Některé projekty používají `HISTORY.txt`, `HISTORY.md`, `History.md`,
|
||||
`NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`,
|
||||
Inu, pokud jste to už nepoznali z příkladu výše, `CHANGELOG.md` je zatím ta
|
||||
nejlepší konvence.
|
||||
|
||||
Některé projekty používají `HISTORY.txt`, `HISTORY.md`, `History.md`,
|
||||
`NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`,
|
||||
`releases.md`, apod.
|
||||
|
||||
Je v tom binec. Všecha tato jména jen komplikují život lidem, kteří se ten
|
||||
dokument snaží najít.
|
||||
|
||||
### Proč lidé jednoduše nepoužívají `git log` diff?
|
||||
Protože diffy logů jsou plné šumu — přirozeně. Nebyly by vyhovujícím
|
||||
changelogem ani v hypotetickém projektu vedeném dokonalými lidmi, kteří nikdy
|
||||
nedělají překlepy, nikdy nezapomínají commitnout nové soubory a nikdy jim
|
||||
neunikne ani ta nejmenší část refactoringu. Cílem commitu je dokumentovat
|
||||
jeden miniaturní krok při procesu, ve kterém se kód vyvíjí z jedné podoby do
|
||||
druhé. Cílem changelogu je dokumentovat podstatné změny mezi těmito podobami.
|
||||
|
||||
Stějně jako je rozdíl mezi dobrými komentáři a samotným kódem, je také rozdíl
|
||||
mezi changelogem a commitlogem: jeden říká *proč* a druhý jak.
|
||||
|
||||
### Mohou být changelogy automaticky parsované?
|
||||
Je to složité, jelikož se lidé uchylují k nejrůznějším formátům a názvům
|
||||
souborů.
|
||||
Je v tom binec. Všecha tato jména jen komplikují život lidem, kteří se ten
|
||||
dokument snaží najít.
|
||||
|
||||
[Vandamme][vandamme] je Ruby gem vytvořený týmem [Gemnasium][gemnasium], který
|
||||
### Proč lidé jednoduše nepoužívají `git log` diff?
|
||||
Protože diffy logů jsou plné šumu — přirozeně. Nebyly by vyhovujícím
|
||||
changelogem ani v hypotetickém projektu vedeném dokonalými lidmi, kteří nikdy
|
||||
nedělají překlepy, nikdy nezapomínají commitnout nové soubory a nikdy jim
|
||||
neunikne ani ta nejmenší část refactoringu. Cílem commitu je dokumentovat
|
||||
jeden miniaturní krok při procesu, ve kterém se kód vyvíjí z jedné podoby do
|
||||
druhé. Cílem changelogu je dokumentovat podstatné změny mezi těmito podobami.
|
||||
|
||||
Stějně jako je rozdíl mezi dobrými komentáři a samotným kódem, je také rozdíl
|
||||
mezi changelogem a commitlogem: jeden říká *proč* a druhý jak.
|
||||
|
||||
### Mohou být changelogy automaticky parsované?
|
||||
Je to složité, jelikož se lidé uchylují k nejrůznějším formátům a názvům
|
||||
souborů.
|
||||
|
||||
[Vandamme][vandamme] je Ruby gem vytvořený týmem [Gemnasium][gemnasium], který
|
||||
parsuje mnoho (ale ne všechny) changelogů open source projektů.
|
||||
|
||||
### Proč používáš jednou "CHANGELOG" a jindy "changelog"?
|
||||
"CHANGELOG" je název samotného souboru. Je to třichu křiklavé, ale to už je
|
||||
historická konvence, kterou se řídí mnoho open source projektů. Příklady
|
||||
podobných souborů mohou být [`README`][README], [`LICENSE`][LICENSE] a
|
||||
"CHANGELOG" je název samotného souboru. Je to třichu křiklavé, ale to už je
|
||||
historická konvence, kterou se řídí mnoho open source projektů. Příklady
|
||||
podobných souborů mohou být [`README`][README], [`LICENSE`][LICENSE] a
|
||||
[`CONTRIBUTING`][CONTRIBUTING].
|
||||
|
||||
Název psaný kapitálkami (díky kterému se ve starých operačních systémech
|
||||
soubory držely na nejvyšších pozicích) je používán za účelem upoutání
|
||||
pozornosti. Vzhledem k tomu, že se jedná o důležitá metadata o projektu a
|
||||
mohla by být užitečná pro kohokoliv, kdo ho chce používat nebo do něho
|
||||
soubory držely na nejvyšších pozicích) je používán za účelem upoutání
|
||||
pozornosti. Vzhledem k tomu, že se jedná o důležitá metadata o projektu a
|
||||
mohla by být užitečná pro kohokoliv, kdo ho chce používat nebo do něho
|
||||
přispívat, podobně [open source projektovým odznakům][shields].
|
||||
|
||||
Když mluvím o "changelogu", myslím tím funkci tohoto souboru: logování změn.
|
||||
|
||||
|
||||
Když mluvím o "changelogu", myslím tím funkci tohoto souboru: logování změn.
|
||||
|
||||
### Jak potom vypadají ta vydání, která byla zpětně stažena?
|
||||
Zpětně 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
|
||||
Zpětně 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ěli takto:
|
||||
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [YANKED]`
|
||||
|
||||
Tag `[YANKED]` je naschvál křiklavý. Je důležité, aby si ho lidé všimli. Díky
|
||||
Tag `[YANKED]` je naschvál křiklavý. Je důležité, aby si ho lidé všimli. Díky
|
||||
tomu, že je v hranatých závorkách je take jednoduší ho parsovat programem.
|
||||
|
||||
### Měl by se někdy changelog přepisovat?
|
||||
Jasně. 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
|
||||
Jasně. 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.
|
||||
|
||||
Je také možné, že zjistíš, že v poznámkách k verzi ve tvém projektu není
|
||||
zmíněna změna, která něco mohla rozbít. V tom případě jě samozřejmě důležité,
|
||||
aby byl changelog aktualizován.
|
||||
Je také možné, že zjistíš, že v poznámkách k verzi ve tvém projektu není
|
||||
zmíněna změna, která něco mohla rozbít. V tom případě jě samozřejmě důležité,
|
||||
aby byl changelog aktualizován.
|
||||
|
||||
### Jak mohu přidat ruku k dílu?
|
||||
Tento dokument není čistá **pravda**; je to můj názor, nad kterým jsem opatrně
|
||||
uvažoval, v kombinaci s informacemi a příklady, které se mi podařilo získat.
|
||||
I přesto, že uvádím vlastní [CHANGELOG][] v [repozitáři na GitHubu][gh],
|
||||
uvažoval, v kombinaci s informacemi a příklady, které se mi podařilo získat.
|
||||
I přesto, že uvádím vlastní [CHANGELOG][] v [repozitáři na GitHubu][gh],
|
||||
naschvál jsem nevytvořil náležité *vydání* nebo jasný seznam pravidel, kterými
|
||||
se někdo má řídit (jako to například udělali na [SemVer.org][semver]).
|
||||
|
||||
Je tomu tak proto, že chci aby komunita došla ke společné shodě. Já sám jsem
|
||||
toho názoru, že diskuse je důležitou součástí finálního výsledku.
|
||||
|
||||
Takže prosím [**přispějte**][gh] svou trochou do mlýna.
|
||||
|
||||
Je tomu tak proto, že chci aby komunita došla ke společné shodě. Já sám jsem
|
||||
toho názoru, že diskuse je důležitou součástí finálního výsledku.
|
||||
|
||||
Takže prosím [**přispějte**][gh] svou trochou do mlýna.
|
||||
|
||||
[CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
|
||||
[CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md
|
||||
|
||||
@ -17,9 +17,8 @@ version: 0.3.0
|
||||
Liste aller erheblichen Änderungen enthält, die zwischen Veröffentlichungen (oder Versionen)
|
||||
des Projekts umgesetzt wurden.
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||
|
||||
:markdown
|
||||
### Was ist der Zweck eines Changelogs?
|
||||
Es Benutzern und Entwicklern einfacher zu machen, gerade die beachtenswerten Änderungen, welche
|
||||
zwischen Veröffentlichungen (oder Versionen) des Projekts gemacht wurden, zu sehen.
|
||||
|
||||
@ -16,9 +16,8 @@ version: 0.3.0
|
||||
A change log is a file which contains a curated, chronologically ordered
|
||||
list of notable changes for each version of a project.
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||
|
||||
:markdown
|
||||
### What’s the point of a change log?
|
||||
To make it easier for users and contributors to see precisely what
|
||||
notable changes have been made between each release (or version) of the project.
|
||||
|
||||
316
source/en/1.0.0/index.html.haml
Normal file
316
source/en/1.0.0/index.html.haml
Normal file
@ -0,0 +1,316 @@
|
||||
---
|
||||
description: Keep a Changelog
|
||||
title: Keep a Changelog
|
||||
language: en
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
|
||||
- gemnasium = "https://gemnasium.com/"
|
||||
- gh = "https://github.com/olivierlacan/keep-a-changelog"
|
||||
- issues = "https://github.com/olivierlacan/keep-a-changelog/issues"
|
||||
- semver = "http://semver.org/"
|
||||
- shields = "http://shields.io/"
|
||||
- thechangelog = "http://5by5.tv/changelog/127"
|
||||
- vandamme = "https://github.com/tech-angels/vandamme/"
|
||||
- iso = "http://www.iso.org/iso/home/standards/iso8601.htm"
|
||||
- ghr = "https://help.github.com/articles/creating-releases/"
|
||||
|
||||
.header
|
||||
.title
|
||||
%h1 Keep a Changelog
|
||||
%h2 Don’t let your friends dump git logs into 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" }
|
||||
What is a changelog?
|
||||
|
||||
%p
|
||||
A changelog is a file which contains a curated, chronologically
|
||||
ordered list of notable changes for each version of a project.
|
||||
|
||||
%h3#why
|
||||
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||||
Why keep a changelog?
|
||||
|
||||
%p
|
||||
To make it easier for users and contributors to see precisely what
|
||||
notable changes have been made between each release (or version) of
|
||||
the project.
|
||||
|
||||
%h3#who
|
||||
%a.anchor{ href: "#who", aria_hidden: "true" }
|
||||
Who needs a changelog?
|
||||
|
||||
%p
|
||||
People do. Whether consumers or developers, the end users of
|
||||
software are human beings who care about what's in the sofware. When
|
||||
the software changes, people want to know why and how.
|
||||
|
||||
.good-practices
|
||||
%h3#how
|
||||
%a.anchor{ href: "#how", aria_hidden: "true" }
|
||||
How do I make a good changelog?
|
||||
|
||||
%h4#principles
|
||||
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
||||
Guiding Principles
|
||||
|
||||
%ul
|
||||
%li
|
||||
Changelogs are <em>for humans</em>, not machines.
|
||||
%li
|
||||
There should be an entry for every single version.
|
||||
%li
|
||||
The same types of changes should be grouped.
|
||||
%li
|
||||
Versions and sections should be linkable.
|
||||
%li
|
||||
The latest version comes first.
|
||||
%li
|
||||
The release date of each versions is displayed.
|
||||
%li
|
||||
Mention whether you follow #{link_to "Semantic Versioning", semver}.
|
||||
|
||||
%a.anchor{ href: "#types", aria_hidden: "true" }
|
||||
%h4#types Types of changes
|
||||
|
||||
%ul
|
||||
%li
|
||||
%code Added
|
||||
for new features.
|
||||
%li
|
||||
%code Changed
|
||||
for changes in existing functionality.
|
||||
%li
|
||||
%code Deprecated
|
||||
for soon-to-be removed features.
|
||||
%li
|
||||
%code Removed
|
||||
for now removed features.
|
||||
%li
|
||||
%code Fixed
|
||||
for any bug fixes.
|
||||
%li
|
||||
%code Security
|
||||
in case of vulnerabilities.
|
||||
|
||||
.effort
|
||||
|
||||
%h3#effort
|
||||
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
||||
How can I reduce the effort required to maintain a changelog?
|
||||
|
||||
%p
|
||||
Keep an <code>Unreleased</code> section at the top to track upcoming
|
||||
changes.
|
||||
|
||||
%p This serves two purposes:
|
||||
|
||||
%ul
|
||||
%li
|
||||
People can see what changes they might expect in upcoming releases
|
||||
%li
|
||||
At release time, you can move the <code>Unreleased</code> section
|
||||
changes into a new release version section.
|
||||
|
||||
.bad-practices
|
||||
%h3#bad-practices
|
||||
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||||
Can changelogs be bad?
|
||||
|
||||
%p Yes. Here are a few ways they can be less than useful.
|
||||
|
||||
%h4#log-diffs
|
||||
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||||
Commit log diffs
|
||||
|
||||
%p
|
||||
Using commit log diffs as changelogs is a bad idea: they're full of
|
||||
noise. Things like merge commits, commits with obscure titles,
|
||||
documentation changes, etc.
|
||||
|
||||
%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.
|
||||
|
||||
%p
|
||||
The purpose of a changelog entry is to document the noteworthy
|
||||
difference, often across multiple commits, to communicate them
|
||||
clearly to end users.
|
||||
|
||||
%h4#ignoring-deprecations
|
||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||
Ignoring Deprecations
|
||||
|
||||
%p
|
||||
When people upgrade from one version to another, it should be
|
||||
painfully clear when something will break. It should be possible to
|
||||
upgrade to a version that lists deprecations, remove what's
|
||||
deprecated, then upgrade to the version where the deprecations
|
||||
become removals.
|
||||
|
||||
%p
|
||||
If you do nothing else, list deprecations, removals, and any
|
||||
breaking changes in your changelog.
|
||||
|
||||
|
||||
%h4#confusing-dates
|
||||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||
Confusing Dates
|
||||
|
||||
%p
|
||||
In the U.S., people put the month first (<code>06-02-2012</code> for
|
||||
June 2nd, 2012), while many people in the rest of the world write a
|
||||
robotic-looking <code>2 June 2012</code>, yet pronounce it
|
||||
differently. <code>2012-06-02</code> works logically from largest to
|
||||
smallest, doesn't overlap in ambiguous ways with other date formats,
|
||||
and is an #{link_to "ISO standard", iso}. Thus, it is the
|
||||
recommended date format for changelogs.
|
||||
|
||||
%aside
|
||||
There’s more. Help me collect these antipatterns by
|
||||
= link_to "opening an issue", "#issues"
|
||||
or a pull request.
|
||||
|
||||
.frequently-asked-questions
|
||||
%h3#frequently-asked-questions
|
||||
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
||||
Frequently Asked Questions
|
||||
|
||||
%h4#standard
|
||||
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
||||
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.
|
||||
|
||||
%p
|
||||
This project aims to be
|
||||
= link_to "a better changelog convention.", changelog
|
||||
It's comes from observing good practices in the open source
|
||||
community and gathering them.
|
||||
|
||||
%p
|
||||
Healthy criticism, discussion and suggestions for improvements
|
||||
= link_to "are welcome.", issues
|
||||
|
||||
|
||||
%h4#filename
|
||||
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
||||
What should the changelog file be named?
|
||||
|
||||
%p
|
||||
Call it <code>CHANGELOG.md</code>. Some projects use
|
||||
<code>HISTORY</code>, <code>NEWS</code> or <code>RELEASES</code>.
|
||||
|
||||
%p
|
||||
While it's easy to think that the name of your changelog file
|
||||
doesn't matter that much, why make it harder for your end users to
|
||||
consistently find notable changes?
|
||||
|
||||
%h4#github-releases
|
||||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||||
What about GitHub Releases?
|
||||
|
||||
%p
|
||||
It's a great initiative. #{link_to "Releases", ghr} can be used to
|
||||
turn simple git tags (for example a tag named <code>v1.0.0</code>)
|
||||
into rich release notes by manually adding release notes or it can
|
||||
pull annotated git tag messages and turn them into notes.
|
||||
|
||||
%p
|
||||
GitHub Releases create a non-portable changelog that can only be
|
||||
displayed to users within the context of GitHub. It's possible to
|
||||
make them look very much like the Keep a Changelog format, but it
|
||||
tends to be a bit more involved.
|
||||
|
||||
%p
|
||||
The current version of GitHub releases is also arguably not very
|
||||
discoverable by end-users, unlike the typical uppercase files
|
||||
(<code>README</code>, <code>CONTRIBUTING</code>, etc.). Another
|
||||
minor issue is that the interface doesn't currently offer links to
|
||||
commit logs between each release.
|
||||
|
||||
%h4#automatic
|
||||
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
||||
Can changelogs be automatically parsed?
|
||||
|
||||
%p
|
||||
It’s difficult, because people follow wildly different formats and
|
||||
file names.
|
||||
|
||||
%p
|
||||
#{link_to "Vandamme", vandamme} is a Ruby gem created by the
|
||||
#{link_to "Gemnasium", gemnasium} team and which parses many (but
|
||||
not all) open source project changelogs.
|
||||
|
||||
|
||||
%h4#yanked
|
||||
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
||||
What about yanked releases?
|
||||
|
||||
%p
|
||||
Yanked releases are versions that had to be pulled because of a
|
||||
serious bug or security issue. Often these versions don't even
|
||||
appear in change logs. They should. This is how you should display
|
||||
them:
|
||||
|
||||
%p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
|
||||
|
||||
%p
|
||||
The <code>[YANKED]</code> tag is loud for a reason. It's important
|
||||
for people to notice it. Since it's surrounded by brackets it's also
|
||||
easier to parse programmatically.
|
||||
|
||||
|
||||
%h4#rewrite
|
||||
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
||||
Should you ever rewrite a changelog?
|
||||
|
||||
%p
|
||||
Sure. There are always good reasons to improve a changelog. I
|
||||
regularly open pull requests to add missing releases to open source
|
||||
projects with unmaintained changelogs.
|
||||
|
||||
%p
|
||||
It's also possible you may discover that you forgot to address a
|
||||
breaking change in the notes for a version. It's obviously important
|
||||
for you to update your changelog in this case.
|
||||
|
||||
|
||||
%h4#contribute
|
||||
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
||||
How can I contribute?
|
||||
|
||||
%p
|
||||
This document is not the <strong>truth</strong>; it’s my carefully
|
||||
considered opinion, along with information and examples I gathered.
|
||||
Although I provide an actual #{link_to "CHANGELOG", changelog} on
|
||||
#{link_to "the GitHub repo", gh}, I have purposefully not created a
|
||||
proper <em>release</em> or clear list of rules to follow (as
|
||||
#{link_to "SemVer.org", semver} does, for instance).
|
||||
|
||||
%p
|
||||
This is because I want our community to reach a consensus. I believe
|
||||
the discussion is as important as the end result.
|
||||
|
||||
%p
|
||||
So please <strong>#{link_to "pitch in", gh}</strong>.
|
||||
|
||||
.press
|
||||
%h3 Conversations
|
||||
%p
|
||||
I went on #{link_to "The Changelog podcast", thechangelog}
|
||||
about why maintainers and contributors should care, and the
|
||||
motivations behind this project. If you can spare the time (1:06),
|
||||
it’s a good listen.
|
||||
@ -16,9 +16,8 @@ version: 0.3.0
|
||||
|
||||
Un registro de cambios o “change log” de ahora en adelante, es un archivo que contiene una lista en orden cronológico sobre los cambios que vamos haciendo en cada reléase (o versión) de nuestro proyecto.
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||
|
||||
:markdown
|
||||
### Cuál es el propósito del change log?
|
||||
|
||||
Para que les sea más fácil a los usuarios y contribuyentes, ver exactamente los cambios notables que se han hecho entre cada versión (o versiones) del proyecto.
|
||||
|
||||
@ -17,9 +17,8 @@ version: 0.3.0
|
||||
une liste triée chronologiquement des changements notables pour chaque
|
||||
version d’un projet
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||
|
||||
:markdown
|
||||
### Quel est l’intérêt d’un change log ?
|
||||
Il permet aux utilisateurs et aux contributeurs de voir plus simplement
|
||||
les changements notables qui ont été réalisés entre chaque publication
|
||||
@ -181,7 +180,7 @@ version: 0.3.0
|
||||
J'ouvre souvent des pull requests pour ajouter des publications manquantes sur
|
||||
des projets open source avec des change logs non-maintenus.
|
||||
|
||||
Il est aussi possible que vous découvriez que vous aviez oublié de mentionner
|
||||
Il est aussi possible que vous découvriez que vous aviez oublié de mentionner
|
||||
un changement majeur dans les notes de version. Il est évidemment important
|
||||
que vous mettiez votre change log à jour dans ce cas.
|
||||
|
||||
|
||||
@ -13,17 +13,16 @@ language: it-IT
|
||||
Un change log è un file che contiene una lista curata e ordinata cronologicamente
|
||||
delle modifiche degne di nota per ogni versione di un progetto.
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||
|
||||
:markdown
|
||||
### A cosa serve un change log?
|
||||
Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche
|
||||
Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche
|
||||
importanti sono state fatte tra ogni release (o versione) del progetto.
|
||||
|
||||
### Perché dovrebbe importarmi?
|
||||
Perché gli strumenti software sono fatti per le persone.
|
||||
Se non ti importa, perché contribuisci all'open source?
|
||||
Di certo ci deve essere un "kernel" (ha!) di interesse
|
||||
Di certo ci deve essere un "kernel" (ha!) di interesse
|
||||
da qualche parte in quel tuo amorevole cervello.
|
||||
|
||||
[Nel podcast "The Changelog" con Adam Stacoviak e Jerod Santo][thechangelog]
|
||||
@ -85,9 +84,9 @@ language: it-IT
|
||||
è raramente d'aiuto. Specialmente se ci sono molte situazioni e casi limite da gestire.
|
||||
|
||||
Questo progetto [contiene ciò che spero diventerà una migliore convenzione per i file CHANGELOG][CHANGELOG].
|
||||
Non credo che lo status quo sia sufficientemente buono, e penso che noi, come comunità,
|
||||
Non credo che lo status quo sia sufficientemente buono, e penso che noi, come comunità,
|
||||
possiamo arrivare a convenzioni migliori se tentiamo di estrarre le pratiche migliori
|
||||
da progetti software reali. Vi consiglio di guardarvi intorno e ricordare che
|
||||
da progetti software reali. Vi consiglio di guardarvi intorno e ricordare che
|
||||
[ogni discussione e suggerimento per migliorare sono sempre benvenuti][issues]!
|
||||
|
||||
### Come si dovrebbe chiamare il file contenente il change log?
|
||||
@ -104,7 +103,7 @@ language: it-IT
|
||||
di digitazione, non dimenticano mai di fare commit dei nuovi file, non dimenticano mai
|
||||
alcuna parte di un refactoring.
|
||||
Lo scopo di un commit è di documentare un passo atomico nel processo di evoluzione del codice
|
||||
da uno stato ad un altro. Lo scopo di un change log è di documentare le differenze
|
||||
da uno stato ad un altro. Lo scopo di un change log è di documentare le differenze
|
||||
degne di nota tra questi stati.
|
||||
|
||||
La differenza tra un change log e un commit log è
|
||||
@ -113,18 +112,18 @@ language: it-IT
|
||||
|
||||
### Si possono analizzare automaticamente i change log?
|
||||
È difficile, perché le persone usano formati e nomi di file profondamente diversi.
|
||||
|
||||
|
||||
[Vandamme][vandamme] è una Ruby gem
|
||||
creata dal team [Gemnasium][gemnasium] ed è in grado di fare il parsing dei
|
||||
change log di molti (ma non tutti) i progetti open source.
|
||||
|
||||
### Perché si alterna tra i nomi "CHANGELOG" e "change log"?
|
||||
"CHANGELOG" è il nome del file. È un po' invadente ma è una
|
||||
"CHANGELOG" è il nome del file. È un po' invadente ma è una
|
||||
convenzione storica seguita da molti progetti open source.
|
||||
Altri esempi di file simili includono [`README`][README], [`LICENSE`][LICENSE],
|
||||
e [`CONTRIBUTING`][CONTRIBUTING].
|
||||
|
||||
I nomi in maiuscolo (che su vecchi sistemi operativi erano ordinati per primi)
|
||||
I nomi in maiuscolo (che su vecchi sistemi operativi erano ordinati per primi)
|
||||
vengono usati per attirare l'attenzione su di essi. Poiché sono metadati
|
||||
importanti relativi al progetto, possono essere utili per chiunque voglia usarlo
|
||||
o contribuire ad esso, un po' come i [badge dei progetti open source][shields].
|
||||
@ -158,7 +157,7 @@ language: it-IT
|
||||
ho volutamente evitato di creare una *release* o una chiara lista di regole
|
||||
da seguire (come fa, ad esempio, [SemVer.org][semver]).
|
||||
|
||||
Questo è perché voglio che la nostra comunità raggiunga un consenso. Credo che
|
||||
Questo è perché voglio che la nostra comunità raggiunga un consenso. Credo che
|
||||
la discussione sia importante almeno quanto il risultato finale.
|
||||
|
||||
Quindi per favore [**partecipate**][gh].
|
||||
|
||||
@ -1,50 +1,74 @@
|
||||
!!! 5
|
||||
%html
|
||||
%head{lang: current_page.data.language}
|
||||
%meta{charset: 'utf-8'}
|
||||
%meta{content: 'IE=edge', 'http-equiv' => 'X-UA-Compatible'}
|
||||
%meta{name: 'viewport', content: 'width=device-width, initial-scale=1.0'}
|
||||
%meta{name: 'description', content: current_page.data.description}
|
||||
%head{ lang: current_page.data.language }
|
||||
%meta{ charset: 'utf-8' }
|
||||
%meta{ content: 'IE=edge', 'http-equiv' => 'X-UA-Compatible' }
|
||||
%meta{ name: 'viewport', content: 'width=device-width, initial-scale=1.0' }
|
||||
%meta{ name: 'description', content: current_page.data.description }
|
||||
|
||||
-# Open Graph
|
||||
|
||||
%meta{property: 'og:article:publisher', content: config.publisher_url}
|
||||
%meta{property: 'og:title', content: current_page.data.title}
|
||||
%meta{property: 'og:type', content: 'article'}
|
||||
%meta{property: 'og:url', content: path_to_url(current_page.url)}
|
||||
%meta{property: 'og:description', content: current_page.data.description}
|
||||
%meta{ property: 'og:article:publisher', content: config.publisher_url }
|
||||
%meta{ property: 'og:title', content: current_page.data.title }
|
||||
%meta{ property: 'og:type', content: 'article' }
|
||||
%meta{ property: 'og:url', content: path_to_url(current_page.url) }
|
||||
%meta{ property: 'og:description', content: current_page.data.description }
|
||||
= yield_content :og
|
||||
|
||||
-# Icons
|
||||
|
||||
%link{rel: 'canonical', href: path_to_url(current_page.url)}
|
||||
%link{ rel: 'canonical', href: path_to_url(current_page.url) }
|
||||
|
||||
%title= current_page.data.title
|
||||
= stylesheet_link_tag '//fonts.googleapis.com/css?family=Carrois+Gothic|Source+Code+Pro:400,700'
|
||||
= stylesheet_link_tag 'application'
|
||||
|
||||
:javascript
|
||||
try{Typekit.load();}catch(e){}
|
||||
%link{ rel: "stylesheet", href: "https://fonts.googleapis.com/css?family=Muli:400,700" }
|
||||
= stylesheet_link_tag '//fonts.googleapis.com/css?family=Source+Code+Pro:400,700'
|
||||
= stylesheet_link_tag 'application'
|
||||
= javascript_include_tag 'all'
|
||||
|
||||
%body
|
||||
%article
|
||||
%header{role: "banner"}
|
||||
%nav.locales{role: "navigation"}
|
||||
%ul
|
||||
%header{ role: "banner" }
|
||||
= image_tag "keep-a-changelog-mark.svg", width: 100, class: "mark"
|
||||
%nav.locales{ role: "navigation" }
|
||||
%select
|
||||
- $languages.each do |language|
|
||||
%li= link_to "#{language.last} [#{language.first}]", "/#{language.first}/",
|
||||
{ rel: "alternate", lang: "#{language.first}", hreflang: "#{language.first}" }
|
||||
- selected = current_page.metadata[:page][:language] == language.first
|
||||
%option{ selected: selected, label: language.last[:name], value: language.first }
|
||||
|
||||
.main{role: "main"}= yield
|
||||
.main{ role: "main" }
|
||||
- if current_page.metadata[:page][:version] != $last_version
|
||||
- code = current_page.metadata[:page][:language]
|
||||
- versions = Dir.entries("source/#{code}") - %w[. ..]
|
||||
- if versions.include?($last_version)
|
||||
= link_to "Version #{$last_version}", "#{code}/#{$last_version}"
|
||||
- else
|
||||
- if $languages[code][:notice]
|
||||
%p.last-version-notice= $languages[code][:notice]
|
||||
- else
|
||||
%p
|
||||
The latest version (#{$last_version}) is not yet available in
|
||||
this language but
|
||||
= link_to "you can read it in English", "/en/#{$last_version}"
|
||||
for now and
|
||||
= link_to "help translate ", "https://github.com/olivierlacan/keep-a-changelog/issues"
|
||||
it.
|
||||
|
||||
%footer.clearfix{role: "banner"}
|
||||
%p.license
|
||||
This project is
|
||||
#{link_to "MIT Licensed", "http://choosealicense.com/licenses/mit/"}.
|
||||
%p.about
|
||||
#{link_to "Typed", "https://github.com/olivierlacan/keep-a-changelog/"}
|
||||
with trepidation by
|
||||
#{link_to "Olivier Lacan", "http://olivierlacan.com/"}.
|
||||
= yield
|
||||
|
||||
%footer.footer.clearfix{ role: "banner" }
|
||||
= image_tag "keep-a-changelog-mark.svg", width: 30, class: "mark"
|
||||
|
||||
%p.about
|
||||
This project is
|
||||
= link_to "MIT Licensed", "http://choosealicense.com/licenses/mit/"
|
||||
\ //
|
||||
= link_to "Created & maintained", "https://github.com/olivierlacan/keep-a-changelog/"
|
||||
by
|
||||
= link_to "Olivier Lacan", "http://olivierlacan.com/"
|
||||
\ //
|
||||
Designed by
|
||||
= link_to "Tyler Fortune", "http://tylerfortune.me/"
|
||||
|
||||
- unless config.gauges_id.blank?
|
||||
:javascript
|
||||
|
||||
144
source/pl-PL/0.3.0/index.html.haml
Normal file
144
source/pl-PL/0.3.0/index.html.haml
Normal file
@ -0,0 +1,144 @@
|
||||
---
|
||||
description: Prowadź Changelog
|
||||
title: Prowadź Changelog
|
||||
language: pl-PL
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
:markdown
|
||||
# Prowadź CHANGELOG
|
||||
|
||||
## Nie pozwól, by twoi znajomi wklejali logi gita do CHANGELOGów™
|
||||
|
||||
Wersja **#{current_page.metadata[:page][:version]}**
|
||||
|
||||
### Czym jest changelog?
|
||||
Changelog, inaczej rejestr zmian lub historia zmian, to plik zawierający chronologicznie uporządkowaną listę istotnych zmian dla każdej wersji projektu.
|
||||
|
||||
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||
|
||||
### Co jest celem prowadzenia changelogu?
|
||||
Changelog pomaga użytkownikom zrozumieć, jakie znaczące zmiany zostały wprowadzone w każdej wersji projektu.
|
||||
|
||||
### Dlaczego miałoby mi zależeć?
|
||||
Ponieważ narzędzia informatyczne są dla ludzi. Jeśli ci nie zależy,
|
||||
dlaczego przyczyniasz się do powstawania otwartego oprogramowania (open source)?
|
||||
|
||||
Rozmawiałem na podcaście ["The Changelog" z Adamem Stacoviakiem i Jerodem Santo][thechangelog]
|
||||
(odpowiednia nazwa, prawda?) o tym, dlaczego osobom wspierającym otwarte programowanie powinno zależeć,
|
||||
oraz o celach samego projektu. Jeśli masz chwilę (1:06), zapraszam do posłuchania - warto.
|
||||
|
||||
### Co składa się na dobry changelog?
|
||||
Cieszę się, że zapytałeś.
|
||||
|
||||
Dobry changelog trzyma się następujących zasad:
|
||||
|
||||
- Jest stworzony dla ludzi, nie maszyn, więc liczy się czytelność.
|
||||
- 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.
|
||||
- Zawsze określaj, czy projekt jest zgodny z [Semantycznym Wersjonowaniem][semver].
|
||||
- Każda wersja powinna:
|
||||
- Zawierać datę w wyżej wymienionym formacie.
|
||||
- Grupować zmiany w celu opisu ich wpływu na projekt, w następujący sposób:
|
||||
- `Added` dla nowych funkcji.
|
||||
- `Changed` dla zmian w istniejącej funkcjonalności.
|
||||
- `Deprecated` (przestarzałe) dla uprzednio stabilnych funkcji, które zostaną usunięte w przyszłych wydaniach projektu.
|
||||
- `Removed` dla przestarzałych funkcji usuniętych w bieżącej wersji.
|
||||
- `Fixed` dla poprawionych błędów (bugów).
|
||||
- `Security` w celu poinformowania użytkowników o zalecanej aktualizacji naprawiającej luki bezpieczeństwa.
|
||||
|
||||
### Jak mogę zminimalizować wysiłek wkładany w prowadzenie changelogu?
|
||||
Zawsze umieszczaj rozdział `"Unreleased"` na szczycie dokumentu, w celu śledzenia wszelkich zmian.
|
||||
|
||||
Ta praktyka ma dwa cele:
|
||||
|
||||
- Użytkownicy widzą, jakich zmian mogą się spodziewać w nadchodzących wydaniach.
|
||||
- W momencie aktualizacji, musisz jedynie zastąpić `"Unreleased"` wersją projektu oraz dodać nowy nagłówek `"Unreleased"` na samej górze.
|
||||
|
||||
### Co sprawia, że jednorożce płaczą?
|
||||
Dobrze... zabierzmy się za to.
|
||||
|
||||
- **Wrzucanie logów diff z zamieszczonymi zmianami.** Po prostu tego nie rób. Nikomu tym nie pomagasz.
|
||||
- **Niewyszczególnianie przestarzałych funkcji.** Użytkownik powinien zostać wyraźnie poinformowany, że coś przestanie działać po aktualizacji.
|
||||
- **Daty w formatach regionalnych.** W USA ludzie zapisują miesiąc na samym początku daty ("06-02-2012" dla 2 czerwca 2012 r.,
|
||||
co nie ma *najmniejszego* sensu), podczas gdy gdzie indziej wiele osób pisze "2 czerwiec 2012", jednak wymawia to w inny sposób.
|
||||
"2012-06-02" to logiczny format zapisywany od największej, do najmniejszej wartości oraz nie pokrywa się z innymi formatami w niejednoznaczny sposób.
|
||||
Jest to jednocześnie [standard ISO](http://www.iso.org/iso/home/standards/iso8601.htm). To wszystko sprawia, że jest to rekomendowany format zapisywania daty w changelogach.
|
||||
|
||||
To jeszcze nie koniec. Pomóż mi zebrać wszystkie łzy jednorożców [zgłaszając problem][issues] lub wprowadzając zmianę poprzez pull request.
|
||||
|
||||
### Czy istnieje standardowy format changelogu?
|
||||
Niestety nie, ale spokojnie. Wiem, że spieszysz wkleić link do tego przewodnika stylu changelogu GNU, czy do dwóch paragrafów "wytycznych" GNU NEWS.
|
||||
Przewodnik stylu GNU to dobry, ale niestety naiwny początek. Nie ma nic złego w byciu naiwnym, ale gdy ludzie potrzebują wytycznych, bycie naiwnym rzadko pomaga.
|
||||
Szczególnie, gdy istnieje wiele sytuacji i szczególnych przypadków z którymi trzeba się zmierzyć.
|
||||
|
||||
Mam nadzieję, że ten projekt zostanie uznany [lepszym standardem pliku CHANGELOG][CHANGELOG].
|
||||
|
||||
Nie uważam, że status quo jest wystarczające i myślę, że jako społeczność, możemy stworzyć lepsze konwencje,
|
||||
jeśli spróbujemy zastosować dobre praktyki stosowane w prawdziwych projektach informatycznych.
|
||||
Proszę, zapoznaj się z projektem i pamiętaj, że [dyskusja i sugestie są zawsze mile widziane][issues]!
|
||||
|
||||
### Jak powinien być nazwany plik changelog?
|
||||
Jeśli nie potrafisz wywnioskować z powyższego przykładu, `CHANGELOG.md` to do tej pory najlepsza konwencja.
|
||||
|
||||
Niektóre projekty również stosują `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
|
||||
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, itd.
|
||||
|
||||
Straszny bałagan. Wszystkie te nazwy sprawiają, że jeszcze ciężej jest odnaleźć ten plik.
|
||||
|
||||
### Dlaczego nie mielibyśmy po prostu stosować raportu `git log`?
|
||||
Ponieważ logi typu diff są z natury zagmatwane. Nawet przy hipotetycznym projekcie stworzonym przez doskonałe istoty ludzkie, które nigdy nie popełniają literówek,
|
||||
nigdy nie zapominają o zsynchronizowaniu nowo dodanych plików czy nigdy niczego nie pomijają podczas refaktoryzacji kodu, logi diff nie mogłyby zastąpić changelogu.
|
||||
Celem `git commit` jest udokumentowanie jednego kroku w procesie, dzięki któremu kod ewoluuje z jednego stanu w kolejny. Celem changelogu jest udokumentowanie tych różnic pomiędzy stanami kodu, które są godne uwagi.
|
||||
|
||||
Różnica między changelogiem a logiem diff, tak samo jak różnica między dobrymi komentarzami a kodem, jest następująca: pierwsze opisuje *dlaczego*, drugie - *jak*.
|
||||
|
||||
### Czy changelog może być generowany automatycznie?
|
||||
To nie takie proste, ponieważ ludzie stosują bardzo różne formaty oraz nazwy plików.
|
||||
|
||||
[Vandamme][vandamme] to gem Ruby stworzony przez ekipę [Gemnasium][gemnasium], parsujący changelogi wielu (ale nie wszystkich) projektów open source.
|
||||
|
||||
### Dlaczego czasem stosujesz pisownię "CHANGELOG", a czasem "changelog"?
|
||||
"CHANGELOG" to nazwa samego pliku. Wygląda to dość głośno, ale taka jest historyczna konwencja przyjęta przez wiele projektów open source. Inne przykłady podobnych plików to [`README`][README], [`LICENSE`][LICENSE],
|
||||
oraz [`CONTRIBUTING`][CONTRIBUTING].
|
||||
|
||||
Zapis wielkimi literami (dzięki któremu w starszych systemach operacyjnch pliki zostają umieszczone na szczycie listy) ma na celu zwrócenie na nie uwagi.
|
||||
Jako że są to ważne informacje dotyczące projektu, mogą być one użyteczne dla każdego, kto zamierza korzystać lub wnieść weń wkład. Ida ta zbliżona jest do [odznaczeń przy projektach open source][shields].
|
||||
|
||||
Gdy stosuję pisownię "changelog", mówię o samej funkcji tego pliku: rejestrowaniu zmian.
|
||||
|
||||
### A co z błędnymi wersjami (yanked)?
|
||||
Są to wersje opublikowane błędnie, czyli takie, które musiały zostać wycofane ze względu na poważny błąd lub lukę bezpieczeństwa. Często takie wersje projektu nie pojawiają się nawet w changelogu, a powinny.
|
||||
Oto jak taka wersja powinna wyglądać:
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [YANKED]`
|
||||
|
||||
Tag `[YANKED]` jest celowo zapisany wielkimi literami. Ważne jest, by został on dostrzeżony. Dzięki temu, że jest ujęty w nawias, może być z łatwością generowany automatycznie.
|
||||
|
||||
### Czy powinno się kiedykolwiek poprawiać changelog?
|
||||
Oczywiście. Zawsze istnieją powody, by ulepszyć changelog. Często zdarza mi się edytować changelogi w projektach open source w których pominięto udokumentowanie istotnych zmian.
|
||||
|
||||
Może się również zdarzyć, że odkryjesz, iż podczas przygotowywania notatek dla wersji projektu, zapomniałeś udokumentować istotną zmianę, która ma wpływ na działanie aplikacji.
|
||||
Ważne jest, by zaktualizować changelog szczególnie jeśli jest to zmiana, która w istotny sposób wpływa na kompatybilność aplikacji.
|
||||
|
||||
### Jak mogę wnieść wkład w projekt?
|
||||
Ten dokument to nie jedna i jedyna **prawda**; to moja starannie sformułowana opinia wraz z informacją i przykładami które zebrałem.
|
||||
Pomimo tego, że prowadzę właściwy [CHANGELOG][] na [GitHubie][gh], celowo nie stworzyłem poprawnego *releasu* czy jasno sprecyzowanych wytycznych (tak jak np. na [SemVer.org][semver]).
|
||||
|
||||
Chcę, by nasza społeczność uzgodniła jak CHANGELOG ma wyglądać. Wierzę, że dyskusja jest niezbędna do osiągnięcia końcowego rezultatu.
|
||||
|
||||
Więc proszę, [**dołącz do projektu**][gh].
|
||||
|
||||
[CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
|
||||
[CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md
|
||||
[LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE
|
||||
[README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md
|
||||
[gemnasium]: https://gemnasium.com/
|
||||
[gh]: https://github.com/olivierlacan/keep-a-changelog
|
||||
[issues]: https://github.com/olivierlacan/keep-a-changelog/issues
|
||||
[semver]: http://semver.org/
|
||||
[shields]: http://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
@ -18,7 +18,7 @@ version: 0.3.0
|
||||
cronologicamente, de mudanças significativas para cada versão de um projeto
|
||||
*open source*.
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||
|
||||
:markdown
|
||||
### Para que serve um *changelog*?
|
||||
@ -165,7 +165,7 @@ version: 0.3.0
|
||||
aparecem em *changelogs*. Deveriam. É assim que você deve exibi-las:
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [YANKED]`
|
||||
|
||||
|
||||
A tag `[YANKED]`/`[REMOVIDA]` é chamativa por uma razão. É importante que
|
||||
as pessoas a notem. Além disso, já que é cercada por colchetes, é mais
|
||||
fácil detectá-la programaticamente.
|
||||
|
||||
@ -18,9 +18,8 @@ version: 0.3.0
|
||||
хронологическом порядке список значимых изменений для каждой версии проекта с
|
||||
открытым исходным кодом.
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||
|
||||
:markdown
|
||||
### Для чего нужен лог изменений?
|
||||
|
||||
Чтобы пользователи и контрибьюторы могли с меньшими усилиями точно
|
||||
|
||||
@ -16,9 +16,8 @@ version: 0.3.0
|
||||
Dnevnik sprememb je datoteka, ki vsebuje kuriran, kronološko urejen
|
||||
seznam opaznih sprememb za vsako verzijo projekta.
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||
|
||||
:markdown
|
||||
### Kaj je smisel dnevnika sprememb?
|
||||
Za poenostavitev, da uporabniki in prispevajoči sodelavci natančno vidijo, katere
|
||||
opazne spremembe so bile narejene med vsako izdajo (ali verzijo) projekta.
|
||||
|
||||
@ -16,9 +16,8 @@ version: 0.3.0
|
||||
En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad
|
||||
lista över ändringar för varje version av ett projekt.
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||
|
||||
:markdown
|
||||
### Vad är meningen med en ändringslogg?
|
||||
För att göra det enkelt för användare och medarbetare att se exakt vilka
|
||||
viktiga ändringar som har gjorts mellan varje utgåva (eller version) av projektet.
|
||||
|
||||
@ -14,9 +14,8 @@ version: 0.3.0
|
||||
Değişiklik kayıtları bir proje için özel olarak hazırlanmış, tarihsel sıralamayla
|
||||
sıralanmış, önemli değişikliklerin bir bütünüdür.
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||
|
||||
:markdown
|
||||
### Değişikliklerin kayıtlarını tutmanın anlamı ne?
|
||||
Bir projenin kullanıcılarının ya da katılımcılarının, dağıtımlar (ya da sürümler)
|
||||
arasındaki tam olarak hangi önemli değişikliklerin olduğunu takip edebilmelerini sağlar.
|
||||
@ -90,7 +89,7 @@ version: 0.3.0
|
||||
Mevcut durumun çok iyi olduğunu düşünmüyorum, ve topluluk olarak, gerçek yazılım
|
||||
projelerinden iyi pratikleri toplayarak bundan daha iyisini yapabiliriz. Lütfen
|
||||
etrafa bir göz gezdirin ve unutmayın [gelişme yolunda tartışmalara ve önerilere her zaman açığız][issues]!
|
||||
|
||||
|
||||
### Değişiklik kayıtlarının dosya ismi ne olmalı?
|
||||
Eh, üstteki örnekten çıkartamadıysanız eğer, `CHANGELOG.md` şu ana kadarki
|
||||
en iyi çözüm.
|
||||
@ -159,7 +158,7 @@ version: 0.3.0
|
||||
[GitHub repo][gh]sunda güncel bir [CHANGELOG][] sağlıyor olsam da, özellikle
|
||||
bir *sürüm* ya da ([SemVer.org][semver] benzeri) takip edilecek kurallar
|
||||
oluşturmadım.
|
||||
|
||||
|
||||
Bunu istememin sebebi topluluğun ortak bir paydada buluşmasını istememdir.
|
||||
İnanıyorum ki tartışmanın kendisi de sonucu kadar önemli.
|
||||
|
||||
|
||||
@ -17,9 +17,8 @@ version: 0.3.0
|
||||
这个列表记录所有版本的重大变动。
|
||||
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||
|
||||
:markdown
|
||||
### 为何要提供更新日志？
|
||||
为了让用户和开发人员更好知道每一个版本有哪些区别。
|
||||
|
||||
|
||||
@ -17,9 +17,8 @@ version: 0.3.0
|
||||
這個列表記錄所有版本的重大變動。
|
||||
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||||
|
||||
:markdown
|
||||
### 為何要提供更新日誌？
|
||||
為了讓用戶和開發人員更好知道每一個版本有哪些區別。
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user