mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-30 09:14:12 +02:00
Merge branch 'master' into feature/favicon
This commit is contained in:
Kewang
GitHub
commit
14314ff82f
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.
|
||||
|
||||
46
CODE_OF_CONDUCT.md
Normal file
46
CODE_OF_CONDUCT.md
Normal file
@ -0,0 +1,46 @@
|
||||
# Contributor Covenant Code of Conduct
|
||||
|
||||
## Our Pledge
|
||||
|
||||
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
|
||||
|
||||
## Our Standards
|
||||
|
||||
Examples of behavior that contributes to creating a positive environment include:
|
||||
|
||||
* Using welcoming and inclusive language
|
||||
* Being respectful of differing viewpoints and experiences
|
||||
* Gracefully accepting constructive criticism
|
||||
* Focusing on what is best for the community
|
||||
* Showing empathy towards other community members
|
||||
|
||||
Examples of unacceptable behavior by participants include:
|
||||
|
||||
* The use of sexualized language or imagery and unwelcome sexual attention or advances
|
||||
* Trolling, insulting/derogatory comments, and personal or political attacks
|
||||
* Public or private harassment
|
||||
* Publishing others' private information, such as a physical or electronic address, without explicit permission
|
||||
* Other conduct which could reasonably be considered inappropriate in a professional setting
|
||||
|
||||
## Our Responsibilities
|
||||
|
||||
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
|
||||
|
||||
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at hi@olivierlacan.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
|
||||
|
||||
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
|
||||
|
||||
## 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]
|
||||
|
||||
[homepage]: http://contributor-covenant.org
|
||||
[version]: http://contributor-covenant.org/version/1/4/
|
||||
@ -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
|
||||
|
||||
@ -17,7 +17,7 @@ This repository generates http://keepachangelog.com/.
|
||||
- `git clone https://github.com/olivierlacan/keep-a-changelog.git`
|
||||
- `cd keep-a-changelog`
|
||||
- `bundle install`
|
||||
- `middleman` starts the local development server at http://localhost:4567
|
||||
- `bundle exec middleman` starts the local development server at http://localhost:4567
|
||||
|
||||
### Deployment
|
||||
- `rake publish` builds and pushes to the `gh-pages` branch
|
||||
|
||||
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,52 +1,76 @@
|
||||
!!! 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:image', content: image_path("logo.png")}
|
||||
%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:image', content: image_path("logo.png") }
|
||||
= yield_content :og
|
||||
|
||||
-# Icons
|
||||
|
||||
%link{rel: "shortcut icon", type: "image/x-icon", href: image_path("favicon.ico")}
|
||||
%link{rel: 'canonical', href: path_to_url(current_page.url)}
|
||||
%link{ rel: "shortcut icon", type: "image/x-icon", href: image_path("favicon.ico") }
|
||||
%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