├── .ruby-version ├── source ├── CNAME ├── assets │ ├── images │ │ ├── logo.png │ │ ├── favicon.ico │ │ ├── bg-hero@2x.png │ │ ├── bg-img1@2x.png │ │ ├── bg-img2@2x.png │ │ ├── keep-a-changelog-mark.svg │ │ └── logo.svg │ ├── stylesheets │ │ ├── anchors.sass │ │ ├── table-of-contents.sass │ │ ├── layout.sass │ │ ├── application.css.sass │ │ ├── legacy.css.sass │ │ ├── sections.sass │ │ └── normalize.css │ └── javascripts │ │ └── all.js ├── zh-CN │ ├── 0.3.0 │ │ └── index.html.haml │ └── 1.0.0 │ │ └── index.html.haml ├── zh-TW │ ├── 0.3.0 │ │ └── index.html.haml │ └── 1.0.0 │ │ └── index.html.haml ├── layouts │ └── layout.html.haml ├── index.html.haml ├── en │ └── 0.3.0 │ │ └── index.html.haml ├── es-ES │ └── 0.3.0 │ │ └── index.html.haml ├── cs │ └── 0.3.0 │ │ └── index.html.haml ├── sl │ └── 0.3.0 │ │ └── index.html.haml ├── tr-TR │ └── 0.3.0 │ │ └── index.html.haml ├── sv │ └── 0.3.0 │ │ └── index.html.haml ├── pl │ └── 0.3.0 │ │ └── index.html.haml ├── it-IT │ └── 0.3.0 │ │ └── index.html.haml ├── ru │ └── 0.3.0 │ │ └── index.html.haml ├── pt-BR │ └── 0.3.0 │ │ └── index.html.haml ├── de │ └── 0.3.0 │ │ └── index.html.haml ├── fr │ └── 0.3.0 │ │ └── index.html.haml └── sk │ └── 1.0.0 │ └── index.html.haml ├── CONTRIBUTING.md ├── .gitignore ├── Rakefile ├── Gemfile ├── .editorconfig ├── LICENSE ├── README.md ├── CODE_OF_CONDUCT.md ├── Gemfile.lock ├── CHANGELOG.md └── config.rb /.ruby-version: -------------------------------------------------------------------------------- 1 | 2.3.1 2 | -------------------------------------------------------------------------------- /source/CNAME: -------------------------------------------------------------------------------- 1 | keepachangelog.com 2 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | See [README](README.md#development). 2 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | /.bundle 3 | /.cache 4 | /.sass-cache 5 | /build 6 | /_site 7 | /.vs 8 | -------------------------------------------------------------------------------- /Rakefile: -------------------------------------------------------------------------------- 1 | require "middleman-gh-pages" 2 | 3 | desc "Build and publish to GitHub Pages" 4 | task :deploy => :publish 5 | -------------------------------------------------------------------------------- /source/assets/images/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Ice3man543/keep-a-changelog/master/source/assets/images/logo.png -------------------------------------------------------------------------------- /source/assets/images/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Ice3man543/keep-a-changelog/master/source/assets/images/favicon.ico -------------------------------------------------------------------------------- /source/assets/images/bg-hero@2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Ice3man543/keep-a-changelog/master/source/assets/images/bg-hero@2x.png -------------------------------------------------------------------------------- /source/assets/images/bg-img1@2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Ice3man543/keep-a-changelog/master/source/assets/images/bg-img1@2x.png -------------------------------------------------------------------------------- /source/assets/images/bg-img2@2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Ice3man543/keep-a-changelog/master/source/assets/images/bg-img2@2x.png -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source "https://rubygems.org" 2 | 3 | gem "addressable" 4 | gem "middleman", "~> 4.1.0" 5 | gem "middleman-autoprefixer" 6 | gem "middleman-blog" 7 | gem "middleman-livereload" 8 | gem "middleman-minify-html" 9 | gem "middleman-syntax" 10 | gem "middleman-gh-pages" 11 | gem "redcarpet" 12 | gem "pry" 13 | -------------------------------------------------------------------------------- /source/assets/stylesheets/anchors.sass: -------------------------------------------------------------------------------- 1 | .anchor 2 | display: none 3 | font-style: normal 4 | font-weight: normal 5 | position: absolute 6 | right: 100% 7 | top: 0 8 | 9 | .anchor::before 10 | line-height: 3.2 11 | content: "∞" 12 | color: $color-ocre 13 | padding-right: 0.1em 14 | 15 | .anchor:hover 16 | a 17 | text-decoration: none 18 | -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | # EditorConfig is awesome: http://EditorConfig.org 2 | # 3 | # All EditorConfig properties: 4 | # https://github.com/editorconfig/editorconfig/wiki/EditorConfig-Properties 5 | 6 | 7 | # Top-most EditorConfig file 8 | root = true 9 | 10 | # This is a small project; currently, we 11 | # use the same settings everywhere 12 | [*] 13 | end_of_line = lf 14 | charset = utf-8 15 | insert_final_newline = true 16 | indent_style = space 17 | indent_size = 2 18 | -------------------------------------------------------------------------------- /source/assets/stylesheets/table-of-contents.sass: -------------------------------------------------------------------------------- 1 | .toc 2 | position: fixed 3 | z-index: 9999 4 | top: 10% 5 | left: 0 6 | 7 | ul 8 | list-style-position: inside 9 | list-style-type: decimal-leading-zero 10 | padding: 0 0 0 1em 11 | li 12 | padding-left: 1em 13 | line-height: 2 14 | a 15 | padding: 0 1em 16 | line-height: 2 17 | display: none 18 | 19 | span 20 | display: none 21 | 22 | li:hover 23 | color: $color-sand 24 | background: $color-black 25 | li:hover a 26 | color: $color-sand 27 | font-weight: bold 28 | background-color: $color-black 29 | display: inline-block 30 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2014 Olivier Lacan 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /source/assets/javascripts/all.js: -------------------------------------------------------------------------------- 1 | document.addEventListener("DOMContentLoaded", function(){ 2 | var select = document.querySelector('.locales select'); 3 | select.addEventListener('change', function(event){ 4 | origin = window.location.origin; 5 | languageCode = event.currentTarget.selectedOptions[0].value 6 | window.location.replace(origin + "/" + languageCode) 7 | }); 8 | 9 | var faqHeaders = document.querySelectorAll('.frequently-asked-questions h4'); 10 | 11 | for (var i = 0; i < faqHeaders.length; ++i) { 12 | header = faqHeaders[i] 13 | header.addEventListener('click', toggleVisibility); 14 | } 15 | 16 | function toggleVisibility(event) { 17 | element = event.target; 18 | element.classList.toggle('is-visible') 19 | 20 | lastParagraph = element.nextElementSibling; 21 | paragraphs = []; 22 | paragraphs.push(lastParagraph); 23 | 24 | while (lastParagraph.nextElementSibling && lastParagraph.nextElementSibling.tagName == "P") { 25 | lastParagraph = lastParagraph.nextElementSibling; 26 | paragraphs.push(lastParagraph) 27 | } 28 | 29 | for (var i = 0; i < paragraphs.length; ++i) { 30 | paragraph = paragraphs[i] 31 | paragraph.classList.toggle('is-visible'); 32 | } 33 | } 34 | }); 35 | -------------------------------------------------------------------------------- /source/assets/stylesheets/layout.sass: -------------------------------------------------------------------------------- 1 | $break-small: em(480px) 2 | $break-medium: em(800px) 3 | $break-large: em(1024px) 4 | 5 | body 6 | margin: 0 7 | 8 | article 9 | margin: 0 auto 10 | max-width: 65em 11 | 12 | .main 13 | background-color: $color-white 14 | 15 | div 16 | padding-left: 5% 17 | padding-right: 5% 18 | padding-bottom: 3em 19 | 20 | aside 21 | background-color: lighten(desaturate($color-bark, 5%), 10%) 22 | margin-bottom: -3em 23 | margin-left: -5% 24 | margin-right: -5% 25 | margin-top: 3em 26 | padding: 2em 5% 27 | text-align: center 28 | 29 | aside & 30 | background-position: top 31 | 32 | article p 33 | font-size: 1.3em 34 | 35 | article code 36 | border-radius: 0.315em 37 | border: 1px solid #ccc 38 | padding: 0 0.3em 0.040em 39 | font-size: 0.9em 40 | 41 | article ul 42 | font-size: 1.1em 43 | line-height: 1.5 44 | list-style-type: square 45 | padding-left: 1em 46 | 47 | @media (min-width: 1077px) 48 | body 49 | margin: 8px 50 | 51 | .main 52 | margin-bottom: 2em 53 | 54 | div 55 | padding-left: 20% 56 | padding-right: 20% 57 | 58 | aside 59 | margin-left: -35% 60 | margin-right: -35% 61 | padding: 2em 20% 62 | -------------------------------------------------------------------------------- /source/assets/stylesheets/application.css.sass: -------------------------------------------------------------------------------- 1 | $base-font-family: 'Muli', "Helvetica Neue", Helvetica, Arial, sans-serif 2 | $source-code-font-family: "Source Code Pro", monospace 3 | 4 | $color-black: #342828 5 | $color-white: #FFFFFF 6 | $color-ocre: #E05735 7 | $color-gold: #faa930 8 | $color-bark: #3F2B2D 9 | $color-sand: #FEECD3 10 | $color-light-sand: lighten($color-sand, 10%) 11 | 12 | @import "layout" 13 | @import "anchors" 14 | @import "sections" 15 | 16 | html 17 | font: 16px/1.4 $base-font-family 18 | color: #342828 19 | background-color: $color-sand 20 | 21 | a 22 | color: $color-ocre 23 | text-decoration: none 24 | 25 | a:hover 26 | text-decoration: underline 27 | 28 | h1 29 | color: $color-ocre 30 | font-size: 3.2em 31 | font-weight: bold 32 | font-family: $base-font-family 33 | margin-bottom: 0 34 | line-height: 1 35 | text-transform: lowercase 36 | 37 | h2 38 | font-size: 1.2em 39 | margin-top: 0.2em 40 | margin-bottom: 2em 41 | 42 | h1, h2 43 | text-align: left 44 | 45 | h3 46 | font-size: 1.3em 47 | font-family: $base-font-family 48 | margin-bottom: 1em 49 | position: relative 50 | padding-left: .1em 51 | 52 | h3:hover .anchor, h3:focus .anchor 53 | display: block 54 | 55 | h3 ~ p 56 | margin-top: 0 57 | 58 | h1, h2, h3 59 | margin-top: 0 60 | padding-top: 1em 61 | 62 | .about 63 | text-align: center 64 | 65 | .about 66 | margin-top: 0 67 | 68 | header 69 | .locales, .mark 70 | margin-bottom: -2em 71 | margin-top: 2em 72 | margin-right: 2em 73 | 74 | .mark 75 | margin-left: 3em 76 | float: left 77 | 78 | .footer 79 | line-height: 2.2 80 | 81 | .mark 82 | float: left 83 | 84 | .locales 85 | float: right 86 | 87 | .locales li 88 | float: right 89 | font-size: 0.7em 90 | display: inline 91 | list-style-type: none 92 | white-space: nowrap 93 | 94 | pre, code 95 | background-color: $color-light-sand 96 | font-family: $source-code-font-family 97 | code 98 | white-space: nowrap 99 | 100 | @media (min-width: 1077px) 101 | h1 102 | width: 50% 103 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Keep a Changelog 2 | 3 | [![version][version-badge]][CHANGELOG] [![license][license-badge]][LICENSE] 4 | 5 | Don’t let your friends dump git logs into changelogs™ 6 | 7 | This repository generates http://keepachangelog.com/. 8 | 9 | ## Development 10 | ### Dependencies 11 | 12 | - Ruby ([see version][ruby-version], [rbenv][rbenv] recommended) 13 | - Bundler (`gem install bundler`) 14 | 15 | ### Installation 16 | 17 | - `git clone https://github.com/olivierlacan/keep-a-changelog.git` 18 | - `cd keep-a-changelog` 19 | - `bundle install` 20 | - `bundle exec middleman` starts the local development server at http://localhost:4567 21 | 22 | ### Deployment 23 | - `bundle exec rake publish` builds and pushes to the `gh-pages` branch 24 | 25 | ### Translations 26 | 27 | Create a new directory in [`source/`][source] named after the ISO 639-1 code 28 | for the language you wish to translate Keep a Changelog to. For example, 29 | assuming you want to translate to French Canadian: 30 | 31 | - create the `source/fr-CA` directory. 32 | - duplicate the `source/en/1.0.0/index.html.haml` file in `source/fr-CA`. 33 | - edit `source/fr-CA/1.0.0/index.html.haml` until your translation is ready. 34 | - commit your changes to your own [fork][fork] 35 | - submit a [Pull Request][pull-request] with your changes 36 | 37 | It may take some time to review your submitted Pull Request. Try to involve a 38 | few native speakers of the language you're translating to in the Pull Request 39 | comments. They'll help review your translation for simple mistakes and give us 40 | a better idea of whether your translation is accurate. 41 | 42 | Thank you for your help improving software one changelog at a time! 43 | 44 | [CHANGELOG]: ./CHANGELOG.md 45 | [LICENSE]: ./LICENSE 46 | [rbenv]: https://github.com/rbenv/rbenv 47 | [ruby-version]: .ruby-version 48 | [source]: source/ 49 | [pull-request]: https://help.github.com/articles/creating-a-pull-request/ 50 | [fork]: https://help.github.com/articles/fork-a-repo/ 51 | [version-badge]: https://img.shields.io/badge/version-1.0.0-blue.svg 52 | [license-badge]: https://img.shields.io/badge/license-MIT-blue.svg 53 | -------------------------------------------------------------------------------- /source/assets/images/keep-a-changelog-mark.svg: -------------------------------------------------------------------------------- 1 | Artboard 1 copy 3 -------------------------------------------------------------------------------- /source/assets/stylesheets/legacy.css.sass: -------------------------------------------------------------------------------- 1 | $base-font-family: "Carrois Gothic", "Helvetica Neue", Helvetica, Arial, sans-serif 2 | $source-code-font-family: "Source Code Pro", monospace 3 | 4 | html 5 | font: 14px/1.4 $base-font-family 6 | color: #333 7 | 8 | a 9 | color: #E10FCE 10 | font-weight: bold 11 | text-decoration: none 12 | 13 | a:hover 14 | text-decoration: underline 15 | 16 | h1 17 | color: #C647BF 18 | font-size: 4.1em 19 | font-weight: bold 20 | font-family: $source-code-font-family 21 | margin-bottom: 0 22 | line-height: 1 23 | word-spacing: -0.3em 24 | 25 | h2 26 | margin-top: 0 27 | margin-bottom: 2em 28 | 29 | h1, h2 30 | text-align: center 31 | 32 | h3 33 | font-size: 1.3em 34 | font-family: $source-code-font-family 35 | margin-bottom: 0 36 | position: relative 37 | padding-left: .1em 38 | 39 | h3:hover .anchor, h3:focus .anchor 40 | display: block 41 | 42 | .anchor 43 | display: none 44 | font-style: normal 45 | font-weight: normal 46 | position: absolute 47 | right: 100% 48 | top: 0 49 | 50 | .anchor::before 51 | content: '¶' 52 | 53 | .anchor:hover 54 | text-decoration: none 55 | 56 | h3 ~ p 57 | margin-top: 0 58 | 59 | article 60 | margin: 0 auto 61 | width: 640px 62 | 63 | article p 64 | font-size: 1.3em 65 | 66 | article code 67 | border-radius: 0.315em 68 | border: 1px solid #ccc 69 | padding: 0 0.3em 0.040em 70 | font-size: 0.9em 71 | 72 | article img 73 | margin: 0 auto 74 | max-width: 100% 75 | text-align: center 76 | display: block 77 | box-shadow: rgba(0, 0, 0, 0.37) 0px 0px 6px 78 | border-radius: 7px 79 | padding: 0.4em 0.9em 80 | 81 | article > ul 82 | font-size: 1.2em 83 | padding-left: 0 84 | 85 | article > ul ul 86 | padding-left: 1em 87 | 88 | article ul 89 | line-height: 1.5 90 | list-style-position: inside 91 | list-style-type: square 92 | 93 | footer 94 | font-size: .7em 95 | border-top: 1px solid #e9e6e1 96 | margin-top: 1em 97 | margin-bottom: 2em 98 | padding-top: 1em 99 | 100 | .license 101 | float: left 102 | 103 | .about 104 | float: right 105 | 106 | .about, .license 107 | margin-top: 0 108 | 109 | .changelog 110 | border: 1px solid #aaa 111 | margin: 0 0.5em 112 | padding: 1em 113 | overflow-x: auto 114 | height: 20em 115 | 116 | .locales li 117 | display: inline 118 | list-style-type: none 119 | padding-right: 20px 120 | white-space: nowrap 121 | 122 | pre, code 123 | font-family: $source-code-font-family 124 | 125 | .newer, .last-version-notice 126 | text-align: center 127 | margin: 1em 128 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | 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. 6 | 7 | ## Our Standards 8 | 9 | Examples of behavior that contributes to creating a positive environment include: 10 | 11 | * Using welcoming and inclusive language 12 | * Being respectful of differing viewpoints and experiences 13 | * Gracefully accepting constructive criticism 14 | * Focusing on what is best for the community 15 | * Showing empathy towards other community members 16 | 17 | Examples of unacceptable behavior by participants include: 18 | 19 | * The use of sexualized language or imagery and unwelcome sexual attention or advances 20 | * Trolling, insulting/derogatory comments, and personal or political attacks 21 | * Public or private harassment 22 | * Publishing others' private information, such as a physical or electronic address, without explicit permission 23 | * Other conduct which could reasonably be considered inappropriate in a professional setting 24 | 25 | ## Our Responsibilities 26 | 27 | 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. 28 | 29 | 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. 30 | 31 | ## Scope 32 | 33 | 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. 34 | 35 | ## Enforcement 36 | 37 | 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. 38 | 39 | 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. 40 | 41 | ## Attribution 42 | 43 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] 44 | 45 | [homepage]: http://contributor-covenant.org 46 | [version]: http://contributor-covenant.org/version/1/4/ 47 | -------------------------------------------------------------------------------- /Gemfile.lock: -------------------------------------------------------------------------------- 1 | GEM 2 | remote: https://rubygems.org/ 3 | specs: 4 | activesupport (5.0.4) 5 | concurrent-ruby (~> 1.0, >= 1.0.2) 6 | i18n (~> 0.7) 7 | minitest (~> 5.1) 8 | tzinfo (~> 1.1) 9 | addressable (2.5.1) 10 | public_suffix (~> 2.0, >= 2.0.2) 11 | autoprefixer-rails (7.1.1.2) 12 | execjs 13 | backports (3.8.0) 14 | coderay (1.1.1) 15 | coffee-script (2.4.1) 16 | coffee-script-source 17 | execjs 18 | coffee-script-source (1.12.2) 19 | compass-import-once (1.0.5) 20 | sass (>= 3.2, < 3.5) 21 | concurrent-ruby (1.0.5) 22 | contracts (0.13.0) 23 | dotenv (2.2.1) 24 | em-websocket (0.5.1) 25 | eventmachine (>= 0.12.9) 26 | http_parser.rb (~> 0.6.0) 27 | erubis (2.7.0) 28 | eventmachine (1.2.0.1) 29 | execjs (2.7.0) 30 | fast_blank (1.0.0) 31 | fastimage (2.1.0) 32 | ffi (1.9.18) 33 | haml (5.0.1) 34 | temple (>= 0.8.0) 35 | tilt 36 | hamster (3.0.0) 37 | concurrent-ruby (~> 1.0) 38 | hashie (3.5.5) 39 | htmlcompressor (0.2.0) 40 | http_parser.rb (0.6.0) 41 | i18n (0.7.0) 42 | kramdown (1.13.2) 43 | listen (3.0.8) 44 | rb-fsevent (~> 0.9, >= 0.9.4) 45 | rb-inotify (~> 0.9, >= 0.9.7) 46 | memoist (0.16.0) 47 | method_source (0.8.2) 48 | middleman (4.1.14) 49 | coffee-script (~> 2.2) 50 | compass-import-once (= 1.0.5) 51 | haml (>= 4.0.5) 52 | kramdown (~> 1.2) 53 | middleman-cli (= 4.1.14) 54 | middleman-core (= 4.1.14) 55 | sass (>= 3.4.0, < 4.0) 56 | middleman-autoprefixer (2.8.0) 57 | autoprefixer-rails (>= 7.0.1, < 8.0.0) 58 | middleman-core (>= 3.3.3) 59 | middleman-blog (4.0.1) 60 | addressable (~> 2.3) 61 | middleman-core (>= 4.0.0) 62 | tzinfo (>= 0.3.0) 63 | middleman-cli (4.1.14) 64 | thor (>= 0.17.0, < 2.0) 65 | middleman-core (4.1.14) 66 | activesupport (>= 4.2, < 5.1) 67 | addressable (~> 2.3) 68 | backports (~> 3.6) 69 | bundler (~> 1.1) 70 | contracts (~> 0.13.0) 71 | dotenv 72 | erubis 73 | execjs (~> 2.0) 74 | fast_blank 75 | fastimage (~> 2.0) 76 | hamster (~> 3.0) 77 | hashie (~> 3.4) 78 | i18n (~> 0.7.0) 79 | listen (~> 3.0.0) 80 | memoist (~> 0.14) 81 | padrino-helpers (~> 0.13.0) 82 | parallel 83 | rack (>= 1.4.5, < 3) 84 | sass (>= 3.4) 85 | servolux 86 | tilt (~> 2.0) 87 | uglifier (~> 3.0) 88 | middleman-gh-pages (0.0.3) 89 | rake (> 0.9.3) 90 | middleman-livereload (3.4.6) 91 | em-websocket (~> 0.5.1) 92 | middleman-core (>= 3.3) 93 | rack-livereload (~> 0.3.15) 94 | middleman-minify-html (3.4.1) 95 | htmlcompressor (~> 0.2.0) 96 | middleman-core (>= 3.2) 97 | middleman-syntax (3.0.0) 98 | middleman-core (>= 3.2) 99 | rouge (~> 2.0) 100 | minitest (5.10.2) 101 | padrino-helpers (0.13.3.4) 102 | i18n (~> 0.6, >= 0.6.7) 103 | padrino-support (= 0.13.3.4) 104 | tilt (>= 1.4.1, < 3) 105 | padrino-support (0.13.3.4) 106 | activesupport (>= 3.1) 107 | parallel (1.11.2) 108 | pry (0.10.3) 109 | coderay (~> 1.1.0) 110 | method_source (~> 0.8.1) 111 | slop (~> 3.4) 112 | public_suffix (2.0.5) 113 | rack (2.0.3) 114 | rack-livereload (0.3.16) 115 | rack 116 | rake (10.4.2) 117 | rb-fsevent (0.9.8) 118 | rb-inotify (0.9.10) 119 | ffi (>= 0.5.0, < 2) 120 | redcarpet (3.4.0) 121 | rouge (2.0.5) 122 | sass (3.4.24) 123 | servolux (0.13.0) 124 | slop (3.6.0) 125 | temple (0.8.0) 126 | thor (0.19.4) 127 | thread_safe (0.3.6) 128 | tilt (2.0.7) 129 | tzinfo (1.2.3) 130 | thread_safe (~> 0.1) 131 | uglifier (3.2.0) 132 | execjs (>= 0.3.0, < 3) 133 | 134 | PLATFORMS 135 | ruby 136 | 137 | DEPENDENCIES 138 | addressable 139 | middleman (~> 4.1.0) 140 | middleman-autoprefixer 141 | middleman-blog 142 | middleman-gh-pages 143 | middleman-livereload 144 | middleman-minify-html 145 | middleman-syntax 146 | pry 147 | redcarpet 148 | 149 | BUNDLED WITH 150 | 1.13.6 151 | -------------------------------------------------------------------------------- /source/zh-CN/0.3.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: 如何维护更新日志 3 | title: 如何维护更新日志 4 | language: zh-CN 5 | version: 0.3.0 6 | --- 7 | 8 | :markdown 9 | # 如何维护更新日志 10 | 11 | ## 更新日志绝对不应该是git日志的堆砌物 12 | 13 | Version **#{current_page.metadata[:page][:version]}** 14 | 15 | ### 更新日志是什么？ 16 | 更新日志（Change Log）是一个由人工编辑，以时间为倒叙的列表。 17 | 这个列表记录所有版本的重大变动。 18 | 19 | 20 | 
#{File.read("CHANGELOG.md")}
21 | 22 | ### 为何要提供更新日志？ 23 | 为了让用户和开发人员更好知道每一个版本有哪些区别。 24 | 25 | ### 为何我要在乎呢？ 26 | 因为归根结底软件是为人提供的。既然你不关心人，那么为何写软件呢？ 27 | 多少你还是要关心你的受众。 28 | 29 | 本文档原作者和另外两个人的一个[播客][thechangelog]向大家介绍了， 30 | 为何代码的管理者和开发者应该在乎更新日志。如果你有一小时时间和很好的英文听力本领， 31 | 不妨听听。 32 | 33 | ### 怎么定义好的更新日志 34 | 好问题！ 35 | 36 | 一个好的更新日志，一定满足： 37 | 38 | - 给人而不是机器写的。记住，要说人话。 39 | - 快速跳转到任意段。所以采用markdown格式 40 | - 一个版本对应一个章节。 41 | - 最新的版本在上，最老的在下面。 42 | - 所有日期采用'YYYY-MM-DD'这种规范。（例如北京奥运会的2008年8月8日是2008-08-08）这个是国际通用，任何语言 43 | 都能理解的，并且还被[xkcd](http://xkcd.com/1179/)推荐呢！ 44 | - 标出来是否遵守[语义化版本格式][semver] 45 | - 每一个软件的版本必须： 46 | - 标明日期（要用上面说过的规范） 47 | - 标明分类（采用英文）。规范如下： 48 | - 'Added' 添加的新功能 49 | - 'Changed' 功能变更 50 | - 'Deprecated' 不建议使用，未来会删掉 51 | - 'Removed' 之前不建议使用的功能，这次真的删掉了 52 | - 'Fixed' 改的bug 53 | - 'Security' 改的有关安全相关bug 54 | 55 | 56 | ### 怎么尽可能减少耗费的精力？ 57 | 永远在文档最上方提供一个'Unreleased' 未发布区域，来记录当前的变化。 58 | 这样作有两大意义。 59 | 60 | - 大家可以看到接下来会有什么变化 61 | - 在发布时，只要把'Unreleased'改为当前版本号，然后再添加一个新的'Unreleased'就行了 62 | 63 | 64 | ### 吐槽环节到了 65 | 请你一定要注意： 66 | 67 | - **把git日志扔到更新日志里。**看似有用，然并卵。 68 | - **不写'deprecations'就删功能。**不带这样坑队友的。 69 | - **采用各种不靠谱日期格式** 2012年12月12日，也就中国人能看懂了。 70 | 71 | 如果你还有要吐槽的，欢迎留[issue][issues]或者直接PR 72 | 73 | 74 | ### 世界上不是有标准的更新日志格式吗？ 75 | 貌似GNU或者GNU NEWS还是提过些规范的，事实是它们太过简陋了。 76 | 开发有那么多种情况，采用那样的规范，确实是不太合适的。 77 | 78 | 这个项目提供的[规范][CHANGELOG]是作者本人希望能够成为世界规范的。 79 | 作者不认为当前的标准足够好，而且作为一个社区，我们是有能力提供更棒的规范。 80 | 如果你对这个规范有不满的地方，不要忘记还可以[吐槽][issues]呢。 81 | 82 | ### 更新日志文件名应该叫什么？ 83 | 84 | 我们的案例中给的名字就是最好的规范：`CHANGELOG.md`，注意大小写。 85 | 86 | 像`HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, 87 | `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`这么 88 | 多文件名就太不统一了。 89 | 90 | 只会让大家更难找到。 91 | 92 | ### 为何不直接记录`git log`? 93 | 94 | 因为git日志一定是乱糟糟的。哪怕一个最理想的由完美的程序员开发和提交的，哪怕一个 95 | 从不忘记每次提交全部文件，不写错别字，不忘记重构每一个部分，也无法保证git日志完美无瑕。 96 | 况且git日志的核心在于记录代码的演化，而更新日志则是记录最重要的变更。 97 | 98 | 就像注释之于代码，更新日志之于git日志。前者解释*为什么*，而后者说明*发生了什么*。 99 | 100 | 101 | ### 更新日志能机器识别吗？ 102 | 非常困难，因为有各种不同的文件格式和其它规范。 103 | 104 | [Vandamme][vandamme]是一个Ruby程序（由[Gemnasium][gemnasium]团队制作），可以解析 105 | 好多种（但绝对不是全部）开源库的更新日志。 106 | 107 | ### 到底是CHANGELOG还是更新日志 108 | 109 | CHANGELOG是文件名，更新日志是常用说法。CHANGELOG采用大写是有历史根源的。就像很多类似的文件 110 | [`README`][README]， [`LICENSE`][LICENSE]，还有[`CONTRIBUTING`][CONTRIBUTING]。 111 | 112 | 采用大写可以更加显著，毕竟这是项目很重要的元信息。就像[开源徽章][shields]。 113 | 114 | ### 那些后来撤下的版本怎么办？ 115 | 因为各种安全/重大bug原因被撤下的版本被标记'YANKED'。这些版本一般不出现在更新日志里，但作者建议他们出现。 116 | 显示方式应该是： 117 | 118 | `## 0.0.5 - 2014-12-13 [YANKED]` 119 | 120 | `[YANKED]`采用大写更加显著，因为这个信息很重要。而采用方括号则容易被程序解析。 121 | 122 | ### 是否可以重写更新日志 123 | 当然。哪怕已经上线了，也可以重新更新更新日志。有许多开源项目更新日志不够新，所以作者就会帮忙更新。 124 | 125 | 另外，很有可能你忘记记录一个重大功能更新。所以这时候应该去重写更新日志。 126 | 127 | ### 如何贡献？ 128 | 本文档并不是**真理**。这只是原作者的个人建议，并且包括许多收集的例子。 129 | 哪怕[本开源库][gh]提供一个[更新日志案例][CHANGELOG]，我刻意没有提供一个 130 | 过于苛刻的规则列表（不像[语义化版本格式][semver]）。 131 | 132 | 这是因为我希望通过社区达到统一观点，我认为中间讨论的过程与结果一样重要。 133 | 134 | 所以[欢迎贡献][gh]。 135 | 136 | 137 | [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md 138 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md 139 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE 140 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md 141 | [gemnasium]: https://gemnasium.com/ 142 | [gh]: https://github.com/olivierlacan/keep-a-changelog 143 | [issues]: https://github.com/olivierlacan/keep-a-changelog/issues 144 | [semver]: http://semver.org/lang/zh-CN/ 145 | [shields]: http://shields.io/ 146 | [thechangelog]: http://5by5.tv/changelog/127 147 | [vandamme]: https://github.com/tech-angels/vandamme/ 148 | -------------------------------------------------------------------------------- /source/assets/stylesheets/sections.sass: -------------------------------------------------------------------------------- 1 | div.header 2 | padding-top: 5em 3 | padding-bottom: 0.1em 4 | background-color: $color-ocre 5 | background-image: image-url("bg-hero@2x.png") 6 | background-size: cover 7 | 8 | h1 9 | color: $color-sand 10 | 11 | h2 12 | font-weight: normal 13 | 14 | a 15 | color: $color-black 16 | 17 | .title 18 | width: 80% 19 | margin: 0 auto 20 | margin-bottom: -2em 21 | 22 | .changelog 23 | background-color: $color-white 24 | box-shadow: 0px 4px 12px 0px hsla(0, 0%, 0%, 0.2) 25 | font-size: 0.8em 26 | height: 20em 27 | margin-bottom: -14em 28 | margin-left: 0.5em 29 | margin-right: 0.5em 30 | margin-top: 1em 31 | overflow-x: auto 32 | padding: 1em 33 | 34 | div.answers 35 | margin-top: 12em 36 | padding-left: 5% 37 | padding-right: 5% 38 | background-color: $color-white 39 | 40 | h3 41 | font-size: 1.7em 42 | color: $color-ocre 43 | 44 | a 45 | color: $color-gold 46 | 47 | p 48 | font-size: 1em 49 | 50 | .good-practices 51 | background-color: $color-gold 52 | background-image: image-url("bg-img1@2x.png") 53 | background-position: bottom left 54 | background-repeat: no-repeat 55 | background-size: 100% 56 | padding-top: 2em 57 | 58 | a.anchor 59 | color: $color-black 60 | 61 | h3 62 | font-size: 1.6em 63 | font-weight: bold 64 | 65 | ul 66 | font-size: 1em 67 | 68 | p 69 | a 70 | color: $color-white 71 | text-decoration: underline 72 | 73 | div.bad-practices 74 | color: $color-white 75 | background-color: $color-bark 76 | background-image: image-url("bg-img2@2x.png") 77 | background-position: bottom left 78 | background-repeat: no-repeat 79 | background-size: 100% 80 | padding-top: 3em 81 | 82 | code 83 | color: $color-black 84 | background-color: desaturate(lighten($color-bark, 50%), 10%) 85 | border: none 86 | 87 | p, aside 88 | a 89 | color: $color-gold 90 | text-decoration: underline 91 | 92 | aside 93 | a 94 | text-decoration: none 95 | 96 | h3 97 | font-size: 1.7em 98 | color: $color-gold 99 | float: left 100 | 101 | 102 | p 103 | clear: left 104 | font-size: 1em 105 | 106 | div.effort 107 | padding-top: 2em 108 | padding-left: 5% 109 | padding-right: 5% 110 | background-color: $color-white 111 | 112 | h3 113 | font-size: 1.6em 114 | font-weight: bold 115 | color: $color-ocre 116 | 117 | div.frequently-asked-questions 118 | padding-top: 2em 119 | padding-left: 5% 120 | padding-right: 5% 121 | background-color: $color-white 122 | 123 | h2 124 | color: $color-ocre 125 | 126 | h3 127 | color: $color-ocre 128 | margin-bottom: 1.5em 129 | font-size: 1.7em 130 | 131 | h4 132 | cursor: pointer 133 | border-bottom: 1px solid transparentize($color-bark, 0.8) 134 | padding: 0 1.1em 1.3em 0 135 | 136 | &:after 137 | content: "⌄" 138 | text-align: right 139 | float: right 140 | font-size: 2.8em 141 | line-height: 0.4 142 | margin-right: -0.3em 143 | 144 | 145 | &.is-visible:after 146 | content: "-" 147 | 148 | h4 ~ p 149 | display: none 150 | font-size: 0.9em 151 | 152 | h4 ~ p.is-visible 153 | display: inherit 154 | 155 | .footer 156 | font-size: .6em 157 | font-weight: normal 158 | border-top: 1px solid #e9e6e1 159 | padding-top: 1em 160 | padding-left: 2em 161 | padding-right: 2em 162 | 163 | background-color: $color-ocre 164 | color: $color-sand 165 | 166 | a 167 | color: $color-white 168 | text-decoration: underline 169 | 170 | &:after 171 | content: "" 172 | display: table 173 | clear: both 174 | 175 | @media (min-width: 1077px) 176 | div.answers 177 | padding-left: 25% 178 | padding-right: 25% 179 | 180 | div.effort 181 | padding-left: 25% 182 | padding-right: 25% 183 | 184 | div.frequently-asked-questions 185 | padding-left: 25% 186 | padding-right: 25% 187 | 188 | .good-practices 189 | h3 190 | width: 50% 191 | h4 192 | padding-left: 15em 193 | ul 194 | padding-left: 16em 195 | 196 | .bad-practices 197 | h3 198 | width: 35% 199 | 200 | h4, p 201 | padding-left: 12em 202 | -------------------------------------------------------------------------------- /source/zh-TW/0.3.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: 如何維護更新日誌 3 | title: 如何維護更新日誌 4 | language: zh-TW 5 | version: 0.3.0 6 | --- 7 | 8 | :markdown 9 | # 如何維護更新日誌 10 | 11 | ## 更新日誌絕對不應該是 git 日誌的堆砌物 12 | 13 | Version **#{current_page.metadata[:page][:version]}** 14 | 15 | ### 更新日誌是什麽？ 16 | 更新日誌（Change Log）是一個由人工編輯，以時間為倒敘的列表。 17 | 這個列表記錄所有版本的重大變動。 18 | 19 | 20 | 
#{File.read("CHANGELOG.md")}
21 | 22 | ### 為何要提供更新日誌？ 23 | 為了讓用戶和開發人員更好知道每一個版本有哪些區別。 24 | 25 | ### 為何我要在乎呢？ 26 | 因為歸根結底軟體是為人提供的。既然你不關心人，那麽為何寫軟體呢？ 27 | 多少你還是要關心你的受眾。 28 | 29 | 本文檔原作者和另外兩個人的一個[部落格][thechangelog]向大家介紹了， 30 | 為何程式碼的管理者和開發者應該在乎更新日誌。如果你有一小時時間和很好的英文聽力本領， 31 | 不妨聽聽。 32 | 33 | ### 怎麽定義好的更新日誌 34 | 好問題！ 35 | 36 | 一個好的更新日誌，一定滿足： 37 | 38 | - 給人而不是機器寫的。記住，要說人話。 39 | - 快速跳轉到任意段。所以採用 markdown 格式 40 | - 一個版本對應一個章節。 41 | - 最新的版本在上面，最舊的在下面。 42 | - 所有日期採用 'YYYY-MM-DD' 這種規範。（例如北京奧運會的 2008 年 8 月 8 日是 2008-08-08）這個是國際通用，任何語言 43 | 都能理解的，並且還被 [xkcd](http://xkcd.com/1179/) 推薦呢！ 44 | - 標出來是否遵守[語義化版本格式][semver] 45 | - 每一個軟體的版本必須： 46 | - 標明日期（要用上面說過的規範） 47 | - 標明分類（採用英文）。規範如下： 48 | - 'Added' 添加的新功能 49 | - 'Changed' 功能變更 50 | - 'Deprecated' 不建議使用，未來會刪掉 51 | - 'Removed' 之前不建議使用的功能，這次真的刪掉了 52 | - 'Fixed' 修正的 bug 53 | - 'Security' 修正了安全相關的 bug 54 | 55 | 56 | ### 怎麽盡可能減少耗費的精力？ 57 | 永遠在文檔最上方提供一個 'Unreleased' 未發布區域，來記錄當前的變化。 58 | 這樣做有兩大意義。 59 | 60 | - 大家可以看到接下來會有什麽變化 61 | - 在發布時，只要把 'Unreleased' 改為當前版本號，然後再添加一個新的 'Unreleased' 就行了 62 | 63 | 64 | ### 吐槽環節到了 65 | 請你一定要注意： 66 | 67 | - **把 git 日誌扔到更新日誌裏。**看似有用，然而並沒有什麼作用。 68 | - **不寫 'deprecations' 就刪功能。**不帶這樣坑隊友的。 69 | - **採用各種不可靠的日期格式** 2012 年 12 月 12 日，也就懂中文的人能看得懂了。 70 | 71 | 如果你還有要吐槽的，歡迎留 [issue][issues] 或者直接 PR 72 | 73 | 74 | ### 世界上不是有標準的更新日誌格式嗎？ 75 | 貌似 GNU 或者 GNU NEWS 還是提過些規範的，事實是它們太過簡陋了。 76 | 開發有那麽多中情況，採用那樣的規範，確實是不太合適的。 77 | 78 | 這個項目提供的[規範][CHANGELOG]是作者本人希望能夠成為世界規範的。 79 | 作者不認為當前的標準足夠好，而且作為一個社區，我們是有能力提供更棒的規範。 80 | 如果你對這個規範有不滿的地方，不要忘記還可以[吐槽][issues]呢。 81 | 82 | ### 更新日誌文件名應該叫什麽？ 83 | 84 | 我們的案例中給的名字就是最好的規範：`CHANGELOG.md`，注意大小寫。 85 | 86 | 像 `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, 87 | `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md` 這麽 88 | 多文件名就太不統一了。 89 | 90 | 只會讓大家更難找到。 91 | 92 | ### 為何不直接記錄 `git log`? 93 | 94 | 因為 git 日誌一定是亂糟糟的。哪怕一個最理想的由完美的程序員開發的提交的，哪怕一個 95 | 從不忘記每次提交全部文件，不寫錯別字，不忘記重構每一個部分——也無法保證 git 日誌完美無瑕。 96 | 況且 git 日誌的核心在於記錄代碼的演化，而更新日誌則是記錄最重要的變更。 97 | 98 | 就像註解之於程式碼，更新日誌之於 git 日誌。前者解釋*為什麽*，而後者說明*發生了什麽*。 99 | 100 | 101 | ### 更新日誌能機器識別嗎？ 102 | 非常困難，因為有各種不同的文件格式和其他規範。 103 | 104 | [Vandamme][vandamme] 是一支 Ruby 程式（由 [Gemnasium][gemnasium] 團隊制作），可以解析 105 | 很多種（但絕對不是全部）開源程式庫的更新日誌。 106 | 107 | ### 到底是 CHANGELOG 還是更新日誌 108 | 109 | CHANGELOG 是文件名，更新日誌是常用說法。CHANGELOG 採用大寫是有歷史根源的。就像很多類似的文件 110 | [`README`][README]，[`LICENSE`][LICENSE]，還有 [`CONTRIBUTING`][CONTRIBUTING]。 111 | 112 | 採用大寫可以更加顯著，畢竟這是項目很重要的 metadata。就像[開源徽章][shields]。 113 | 114 | ### 那些後來撤下的版本怎麽辦？ 115 | 因為各種安全/重大 bug 原因被撤下的版本被標記 'YANKED'。這些版本一般不出現在更新日誌裏，但作者建議他們出現。 116 | 顯示方式應該是： 117 | 118 | `## 0.0.5 - 2014-12-13 [YANKED]` 119 | 120 | `[YANKED]` 採用大寫更加顯著，因為這個訊息很重要。而採用方括號則容易被程式解析。 121 | 122 | ### 是否可以重寫更新日誌 123 | 當然。哪怕已經上線了，也可以重新更新更新日誌。有許多開源項目更新日誌不夠新，所以作者就會幫忙更新。 124 | 125 | 另外，很有可能你忘記記錄一個重大功能更新。所以這時候應該去重寫更新日誌。 126 | 127 | ### 如何貢獻？ 128 | 本文檔並不是**真理**。這只是原作者的個人建議，並且包括許多收集的例子。 129 | 哪怕[本開源庫][gh]提供一個[更新日誌案例][CHANGELOG]，我刻意沒有提供一個 130 | 過於苛刻的規則列表（不像[語義化版本格式][semver]）。 131 | 132 | 這是因為我希望通過社區達到統一觀點，我認為中間討論的過程與結果一樣重要。 133 | 134 | 所以[歡迎貢獻][gh]。 135 | 136 | 137 | [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md 138 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md 139 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE 140 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md 141 | [gemnasium]: https://gemnasium.com/ 142 | [gh]: https://github.com/olivierlacan/keep-a-changelog 143 | [issues]: https://github.com/olivierlacan/keep-a-changelog/issues 144 | [semver]: http://semver.org/lang/zh-CN/ 145 | [shields]: http://shields.io/ 146 | [thechangelog]: http://5by5.tv/changelog/127 147 | [vandamme]: https://github.com/tech-angels/vandamme 148 | -------------------------------------------------------------------------------- /source/layouts/layout.html.haml: -------------------------------------------------------------------------------- 1 | // Variables 2 | - latest_version = current_page.metadata[:page][:version] == $last_version 3 | - language_code = current_page.metadata[:page][:language] 4 | - versions = Dir.entries("source/#{language_code}") - %w[. ..] 5 | - current_version = current_page.metadata[:page][:version] 6 | - newer_version_available = File.exists?("source/#{language_code}/#{$last_version}") 7 | 8 | !!! 5 9 | %html 10 | %head{ lang: current_page.data.language } 11 | %meta{ charset: 'utf-8' } 12 | %meta{ content: 'IE=edge', 'http-equiv' => 'X-UA-Compatible' } 13 | %meta{ name: 'viewport', content: 'width=device-width, initial-scale=1.0' } 14 | %meta{ name: 'description', content: current_page.data.description } 15 | 16 | -# Open Graph 17 | 18 | %meta{ property: 'og:article:publisher', content: config.publisher_url } 19 | %meta{ property: 'og:title', content: current_page.data.title } 20 | %meta{ property: 'og:type', content: 'article' } 21 | %meta{ property: 'og:url', content: path_to_url(current_page.url) } 22 | %meta{ property: 'og:description', content: current_page.data.description } 23 | %meta{ property: 'og:image', content: image_path("logo.png") } 24 | = yield_content :og 25 | 26 | -# Icons 27 | 28 | %link{ rel: "shortcut icon", type: "image/x-icon", href: image_path("favicon.ico") } 29 | %link{ rel: 'canonical', href: path_to_url(current_page.url) } 30 | 31 | %title= current_page.data.title 32 | 33 | %link{ rel: "stylesheet", href: "https://fonts.googleapis.com/css?family=Muli:400,700" } 34 | = stylesheet_link_tag '//fonts.googleapis.com/css?family=Source+Code+Pro:400,700' 35 | - if latest_version 36 | = stylesheet_link_tag 'application' 37 | - else 38 | = stylesheet_link_tag 'legacy' 39 | = javascript_include_tag 'all', defer: true 40 | 41 | %body 42 | %article 43 | %header{ role: "banner" } 44 | - if latest_version 45 | = image_tag "keep-a-changelog-mark.svg", width: 100, class: "mark" 46 | %nav.locales{ role: "navigation" } 47 | %select 48 | - $languages.each do |language| 49 | - selected = language_code == language.first 50 | - if available_translation = available_translation_for(language) 51 | %option{ selected: selected, label: available_translation, value: language.first } 52 | = available_translation 53 | 54 | .main{ role: "main" } 55 | - if !latest_version 56 | - if versions.include?($last_version) 57 | %p.newer 58 | - if $languages[language_code][:new] 59 | = "#{$languages[language_code][:new]}: " 60 | - else 61 | There is a newer version available: 62 | = link_to "#{$languages[language_code][:name]} #{$last_version}", "/#{language_code}/#{$last_version}" 63 | - else 64 | - if $languages[language_code][:notice] 65 | %p.last-version-notice= $languages[language_code][:notice] 66 | - else 67 | %p.last-version-notice 68 | The latest version (#{$last_version}) is not yet available in 69 | this language but 70 | = link_to "you can read it in English", "/en/#{$last_version}" 71 | for now and 72 | = link_to "help translate ", "https://github.com/olivierlacan/keep-a-changelog/issues" 73 | it. 74 | 75 | = yield 76 | 77 | %footer.footer.clearfix{ role: "banner" } 78 | = image_tag "keep-a-changelog-mark.svg", width: 30, class: "mark" 79 | 80 | %p.about 81 | This project is 82 | = link_to "MIT Licensed", "http://choosealicense.com/licenses/mit/" 83 | \ // 84 | = link_to "Created & maintained", "https://github.com/olivierlacan/keep-a-changelog/" 85 | by 86 | = link_to "Olivier Lacan", "http://olivierlacan.com/" 87 | \ // 88 | Designed by 89 | = link_to "Tyler Fortune", "http://tylerfortune.me/" 90 | 91 | - unless config.gauges_id.blank? 92 | :javascript 93 | var _gauges = _gauges || []; 94 | (function() { 95 | var t = document.createElement('script'); 96 | t.type = 'text/javascript'; 97 | t.async = true; 98 | t.id = 'gauges-tracker'; 99 | t.setAttribute('data-site-id', '#{config.gauges_id}'); 100 | t.src = '//secure.gaug.es/track.js'; 101 | var s = document.getElementsByTagName('script')[0]; 102 | s.parentNode.insertBefore(t, s); 103 | })(); 104 | -------------------------------------------------------------------------------- /source/assets/images/logo.svg: -------------------------------------------------------------------------------- 1 | Artboard 1 -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | All notable changes to this project will be documented in this file. 3 | 4 | The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) 5 | and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). 6 | 7 | ## [Unreleased] 8 | 9 | ## [1.0.0] - 2017-06-20 10 | ### Added 11 | - New visual identity by @tylerfortune8. 12 | - Version navigation. 13 | - Links to latest released version in previous versions. 14 | - "Why keep a changelog?" section. 15 | - "Who needs a changelog?" section. 16 | - "How do I make a changelog?" section. 17 | - "Frequently Asked Questions" section. 18 | - New "Guiding Principles" sub-section to "How do I make a changelog?". 19 | - Simplified and Traditional Chinese translations from @tianshuo. 20 | - German translation from @mpbzh & @Art4. 21 | - Italian translation from @azkidenz. 22 | - Swedish translation from @magol. 23 | - Turkish translation from @karalamalar. 24 | - French translation from @zapashcanon. 25 | - Brazilian Portugese translation from @aisamu. 26 | - Polish translation from @amielucha. 27 | - Russian translation from @aishek. 28 | - Czech translation from @h4vry. 29 | - Slovak translation from @jkostolansky. 30 | 31 | ### Changed 32 | - Start using "changelog" over "change log" since it's the common usage. 33 | - Start versioning based on the current English version at 0.3.0 to help 34 | translation authors keep things up-to-date. 35 | - Rewrite "What makes unicorns cry?" section. 36 | - Rewrite "Ignoring Deprecations" sub-section to clarify the ideal 37 | scenario. 38 | - Improve "Commit log diffs" sub-section to further argument against 39 | them. 40 | - Merge "Why can’t people just use a git log diff?" with "Commit log 41 | diffs" 42 | - Fix typos in Simplified Chinese and Traditional Chinese translations. 43 | - Fix typos in Brazilian Portugese translation. 44 | - Fix typos in Turkish translation. 45 | - Fix typos in Czech translation. 46 | - Fix typos in Swedish translation. 47 | - Improve phrasing in French translation. 48 | - Fix phrasing and spelling in German translation. 49 | 50 | ### Removed 51 | - Section about "changelog" vs "CHANGELOG". 52 | 53 | ## [0.3.0] - 2015-12-03 54 | ### Added 55 | - RU translation from @aishek. 56 | - pt-BR translation from @tallesl. 57 | - es-ES translation from @ZeliosAriex. 58 | 59 | ## [0.2.0] - 2015-10-06 60 | ### Changed 61 | - Remove exclusionary mentions of "open source" since this project can 62 | benefit both "open" and "closed" source projects equally. 63 | 64 | ## [0.1.0] - 2015-10-06 65 | ### Added 66 | - Answer "Should you ever rewrite a change log?". 67 | 68 | ### Changed 69 | - Improve argument against commit logs. 70 | - Start following [SemVer](http://semver.org) properly. 71 | 72 | ## [0.0.8] - 2015-02-17 73 | ### Changed 74 | - Update year to match in every README example. 75 | - Reluctantly stop making fun of Brits only, since most of the world 76 | writes dates in a strange way. 77 | 78 | ### Fixed 79 | - Fix typos in recent README changes. 80 | - Update outdated unreleased diff link. 81 | 82 | ## [0.0.7] - 2015-02-16 83 | ### Added 84 | - Link, and make it obvious that date format is ISO 8601. 85 | 86 | ### Changed 87 | - Clarified the section on "Is there a standard change log format?". 88 | 89 | ### Fixed 90 | - Fix Markdown links to tag comparison URL with footnote-style links. 91 | 92 | ## [0.0.6] - 2014-12-12 93 | ### Added 94 | - README section on "yanked" releases. 95 | 96 | ## [0.0.5] - 2014-08-09 97 | ### Added 98 | - Markdown links to version tags on release headings. 99 | - Unreleased section to gather unreleased changes and encourage note 100 | keeping prior to releases. 101 | 102 | ## [0.0.4] - 2014-08-09 103 | ### Added 104 | - Better explanation of the difference between the file ("CHANGELOG") 105 | and its function "the change log". 106 | 107 | ### Changed 108 | - Refer to a "change log" instead of a "CHANGELOG" throughout the site 109 | to differentiate between the file and the purpose of the file — the 110 | logging of changes. 111 | 112 | ### Removed 113 | - Remove empty sections from CHANGELOG, they occupy too much space and 114 | create too much noise in the file. People will have to assume that the 115 | missing sections were intentionally left out because they contained no 116 | notable changes. 117 | 118 | ## [0.0.3] - 2014-08-09 119 | ### Added 120 | - "Why should I care?" section mentioning The Changelog podcast. 121 | 122 | ## [0.0.2] - 2014-07-10 123 | ### Added 124 | - Explanation of the recommended reverse chronological release ordering. 125 | 126 | ## 0.0.1 - 2014-05-31 127 | ### Added 128 | - This CHANGELOG file to hopefully serve as an evolving example of a 129 | standardized open source project CHANGELOG. 130 | - CNAME file to enable GitHub Pages custom domain 131 | - README now contains answers to common questions about CHANGELOGs 132 | - Good examples and basic guidelines, including proper date formatting. 133 | - Counter-examples: "What makes unicorns cry?" 134 | 135 | [Unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...HEAD 136 | [1.0.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0 137 | [0.3.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.2.0...v0.3.0 138 | [0.2.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.2.0 139 | [0.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.8...v0.1.0 140 | [0.0.8]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.7...v0.0.8 141 | [0.0.7]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.6...v0.0.7 142 | [0.0.6]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.5...v0.0.6 143 | [0.0.5]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.4...v0.0.5 144 | [0.0.4]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.3...v0.0.4 145 | [0.0.3]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.2...v0.0.3 146 | [0.0.2]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.1...v0.0.2 147 | -------------------------------------------------------------------------------- /source/zh-CN/1.0.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: 如何维护更新日志 3 | title: 如何维护更新日志 4 | language: zh-CN 5 | version: 1.0.0 6 | --- 7 | 8 | - changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md" 9 | - gemnasium = "https://gemnasium.com/" 10 | - gh = "https://github.com/olivierlacan/keep-a-changelog" 11 | - issues = "https://github.com/olivierlacan/keep-a-changelog/issues" 12 | - semver = "http://semver.org/" 13 | - shields = "http://shields.io/" 14 | - thechangelog = "http://5by5.tv/changelog/127" 15 | - vandamme = "https://github.com/tech-angels/vandamme/" 16 | - iso = "http://www.iso.org/iso/home/standards/iso8601.htm" 17 | - ghr = "https://help.github.com/articles/creating-releases/" 18 | 19 | .header 20 | .title 21 | %h1 如何维护更新日志 22 | %h2 更新日志绝对不应该是git日志的堆砌物 23 | 24 | = link_to changelog do 25 | Version 26 | %strong= current_page.metadata[:page][:version] 27 | 28 | %pre.changelog= File.read("CHANGELOG.md") 29 | 30 | .answers 31 | %h3#what 32 | %a.anchor{ href: "#what", aria_hidden: "true" } 33 | 更新日志是什么？ 34 | 35 | %p 36 | 更新日志（Change Log）是一个由人工编辑，以时间为倒叙的列表， 37 | 以记录一个项目中所有版本的显著变动。 38 | 39 | %h3#why 40 | %a.anchor{ href: "#why", aria_hidden: "true" } 41 | 为何要提供更新日志？ 42 | 43 | %p 44 | 为了让用户和开发人员更简单明确的知晓项目在不同版本之间有哪些显著变动。 45 | 46 | %h3#who 47 | %a.anchor{ href: "#who", aria_hidden: "true" } 48 | 哪些人需要更新日志？ 49 | 50 | %p 51 | 人人需要更新日志。无论是消费者还是开发者，软件的最终用户都关心软件所包含什么。 52 | 当软件有所变动时，大家希望知道改动是为何、以及如何进行的。 53 | 54 | .good-practices 55 | %h3#how 56 | %a.anchor{ href: "#how", aria_hidden: "true" } 57 | 怎样制作高质量的更新日志？ 58 | 59 | %h4#principles 60 | %a.anchor{ href: "#principles", aria_hidden: "true" } 61 | 指导原则 62 | 63 | %ul 64 | %li 65 | 记住日志是写给人的，而非机器。 66 | %li 67 | 每个版本都应该有独立的入口。 68 | %li 69 | 同类改动应该分组放置。 70 | %li 71 | 版本与章节应该相互对应。 72 | %li 73 | 新版本在前，旧版本在后。 74 | %li 75 | 应包括每个版本的发布日期。 76 | %li 77 | 注明是否遵守#{link_to "语义化版本格式", semver}. 78 | 79 | %a.anchor{ href: "#types", aria_hidden: "true" } 80 | %h4#types 变动类型 81 | 82 | %ul 83 | %li 84 | %code Added 85 | 新添加的功能。 86 | %li 87 | %code Changed 88 | 对现有功能的变更。 89 | %li 90 | %code Deprecated 91 | 已经不建议使用，准备很快移除的功能。 92 | %li 93 | %code Removed 94 | 已经移除的功能。 95 | %li 96 | %code Fixed 97 | 对bug的修复 98 | %li 99 | %code Security 100 | 对安全的改进 101 | 102 | .effort 103 | 104 | %h3#effort 105 | %a.anchor{ href: "#effort", aria_hidden: "true" } 106 | 如何减少维护更新日志的精力？ 107 | 108 | %p 109 | 在文档最上方提供 Unreleased 区块以记录即将发布的更新内容。 110 | 111 | %p 这样有两大意义： 112 | 113 | %ul 114 | %li 115 | 大家可以知道在未来版本中可能会有哪些变更 116 | %li 117 | 在发布新版本时，可以直接将Unreleased区块中的内容移动至新发 118 | 布版本的描述区块就可以了 119 | 120 | .bad-practices 121 | %h3#bad-practices 122 | %a.anchor{ href: "#bad-practices", aria_hidden: "true" } 123 | 有很糟糕的更新日志吗？ 124 | 125 | %p 当然有，下面就是一些糟糕的方式。 126 | 127 | %h4#log-diffs 128 | %a.anchor{ href: "#log-diffs", aria_hidden: "true" } 129 | 使用git日志 130 | 131 | %p 132 | 使用git日志作为更新日志是个非常糟糕的方式：git日志充满各种无意义的信息， 133 | 如合并提交、语焉不详的提交标题、文档更新等。 134 | 135 | %p 136 | 提交的目的是记录源码的演化。 137 | 一些项目会清理提交记录，一些则不会。 138 | 139 | %p 140 | 更新日志的目的则是记录重要的变更以供最终受众阅读，而记录范围通常涵盖多次提交。 141 | 142 | %h4#ignoring-deprecations 143 | %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } 144 | 无视即将弃用功能 145 | 146 | %p 147 | 当从一个版本升级至另一个时，人们应清楚（尽管痛苦）的知道哪些部分将出现问题。 148 | 应该允许先升级至一个列出哪些功能将会被弃用的版本，待去掉那些不再支持的部分后， 149 | 再升级至把那些弃用功能真正移除的版本。 150 | 151 | %p 152 | 即使其他什么都不做，也要在更新日志中列出derecations，removals以及其他重大变动。 153 | 154 | %h4#confusing-dates 155 | %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } 156 | 易混淆的日期格式 157 | 158 | %p 159 | 在美国，人们将月份写在日期的起始(06-02-2012对应2012年6月2日)， 160 | 与此同时世界上其他地方的很多人将至写作2 June 2012，并拥有不同发音。 161 | 2012-06-02从大到小的排列符合逻辑，并不与其他日期格式相混淆，而且还 162 | 符合#{link_to "ISO标准", iso}。因此，推荐在更新日志中采用使用此种日期格式。 163 | 164 | %aside 165 | 还有更多内容。请通过 166 | = link_to "发布问题", issues 167 | 或发布pull请求帮助我收集更多异常模式。 168 | 169 | .frequently-asked-questions 170 | %h3#frequently-asked-questions 171 | %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" } 172 | 常见问题 173 | 174 | %h4#standard 175 | %a.anchor{ href: "#standard", aria_hidden: "true" } 176 | 是否有一个标准化的更新日志格式？ 177 | 178 | %p 179 | 并没有。虽然GNU提供了更新日志样式指引，以及那个仅有两段长的GNU NEWS文件“指南”， 180 | 但两者均远远不够。 181 | 182 | %p 183 | 此项目意在提供一个 184 | = link_to "更好的更新日志惯例", changelog 185 | 所有点子都来自于在开源社区中对优秀实例的观察与记录。 186 | 187 | %p 188 | 对于所有建设性批评、讨论及建议，我们都非常 189 | = link_to "欢迎。", issues 190 | 191 | 192 | %h4#filename 193 | %a.anchor{ href: "#filename", aria_hidden: "true" } 194 | 更新日志文件应被如何命名？ 195 | 196 | %p 197 | 可以叫做CHANGELOG.md。 一些项目也使用 198 | HISTORY、NEWS或RELEASES。 199 | 200 | %p 201 | 当然，你可以认为更新日志的名字并不是什么要紧事，但是为什么要为难那些仅仅是 202 | 想看到都有哪些重大变更的最终用户呢？ 203 | 204 | %h4#github-releases 205 | %a.anchor{ href: "#github-releases", aria_hidden: "true" } 206 | 对于GitHub发布呢？ 207 | 208 | %p 209 | 这是个非常好的倡议。#{link_to "Releases", ghr}可通过手动添加发布日志或将带 210 | 有注释的git标签信息抓取后转换的方式，将简单的git标签（如一个叫v1.0.0的标签） 211 | 转换为信息丰富的发布日志。 212 | 213 | %p 214 | GitHub发布会创建一个非便携、仅可在GitHub环境下显示的更新日志。尽管会花费更 215 | 多时间，但将之处理成更新日志格式是完全可能的。 216 | 217 | %p 218 | 现行版本的GitHub发布不像哪些典型的大写文件(README, 219 | CONTRIBUTING, etc.)，仍可以认为是不利于最终用户探索的。 220 | 另一个小问题则是界面并不提供不同版本间commit日志的链接。 221 | 222 | %h4#automatic 223 | %a.anchor{ href: "#automatic", aria_hidden: "true" } 224 | 更新日志可以被自动识别吗？ 225 | 226 | %p 227 | 非常困难，因为有各种不同的文件格式和命名。 228 | 229 | 230 | %p 231 | #{link_to "Vandamme", vandamme} 是一个Ruby程序，由 232 | #{link_to "Gemnasium", gemnasium} 团队制作，可以解析多种 233 | （但绝对不是全部）开源库的更新日志。 234 | 235 | 236 | %h4#yanked 237 | %a.anchor{ href: "#yanked", aria_hidden: "true" } 238 | 那些后来撤下的版本怎么办？ 239 | 240 | %p 241 | 因为各种安全/重大bug原因被撤下的版本被标记'YANKED'。 242 | 这些版本一般不出现在更新日志里，但建议他们出现。 243 | 显示方式应该是： 244 | 245 | %p ## 0.0.5 - 2014-12-13 [YANKED] 246 | 247 | %p 248 | [YANKED] 的标签应该非常醒目。 249 | 人们应该非常容易就可以注意到他。 250 | 并且被方括号所包围也使其更易被程序识别。 251 | 252 | 253 | %h4#rewrite 254 | %a.anchor{ href: "#rewrite", aria_hidden: "true" } 255 | 是否可以重写更新日志？ 256 | 257 | %p 258 | 当然可以。总会有多种多样的原因需要我们去改进更新日志。 259 | 对于那些有着未维护更新日志的开源项目，我会定期打开pull请求以加入缺失的发布信息。 260 | 261 | %p 262 | 另外，很有可能你发现自己忘记记录一个重大功能更新。这种情况下显然你应该去重写更新日志。 263 | 264 | 265 | %h4#contribute 266 | %a.anchor{ href: "#contribute", aria_hidden: "true" } 267 | 如何贡献？ 268 | 269 | %p 270 | 本文档并非真理。而是我深思熟虑后的建议，以及我收集的信息与典例。 271 | 272 | %p 273 | 我希望我们的社区可以对此达成一直。我相信讨论的过程与最终结果一样重要。 274 | 275 | %p 276 | 所以欢迎#{link_to "贡献", gh}. 277 | 278 | .press 279 | %h3 访谈 280 | %p 281 | 我在#{link_to "更新日志播客", thechangelog}上讲述了为何维护者与贡献者应关心更新日志， 282 | 以及支持我进行此项目的诸多因素。 283 | -------------------------------------------------------------------------------- /source/zh-TW/1.0.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: 如何維護更新日誌 3 | title: 如何維護更新日誌 4 | language: zh-TW 5 | version: 1.0.0 6 | --- 7 | 8 | - changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md" 9 | - gemnasium = "https://gemnasium.com/" 10 | - gh = "https://github.com/olivierlacan/keep-a-changelog" 11 | - issues = "https://github.com/olivierlacan/keep-a-changelog/issues" 12 | - semver = "http://semver.org/lang/zh-TW/" 13 | - shields = "http://shields.io/" 14 | - thechangelog = "http://5by5.tv/changelog/127" 15 | - vandamme = "https://github.com/tech-angels/vandamme/" 16 | - iso = "http://www.iso.org/iso/home/standards/iso8601.htm" 17 | - ghr = "https://help.github.com/articles/creating-releases/" 18 | - gnu_changelog_styleguide = "https://www.gnu.org/prep/standards/html_node/Change-Logs.html" 19 | - gnu_the_news = "https://www.gnu.org/prep/standards/html_node/NEWS-File.html" 20 | 21 | .header 22 | .title 23 | %h1 如何維護更新日誌 24 | %h2 更新日誌絕對不應該只是 git log 的堆砌物 25 | 26 | = link_to changelog do 27 | Version 28 | %strong= current_page.metadata[:page][:version] 29 | 30 | %pre.changelog= File.read("CHANGELOG.md") 31 | 32 | .answers 33 | %h3#what 34 | %a.anchor{ href: "#what", aria_hidden: "true" } 35 | 更新日誌是什麼？ 36 | 37 | %p 38 | 更新日誌（Changelog）是個記錄專案演進版本間的差異，以時間倒敘、由人工攥寫的列表。 39 | 40 | %h3#why 41 | %a.anchor{ href: "#why", aria_hidden: "true" } 42 | 為什麼需要提供更新日誌？ 43 | 44 | %p 45 | 為了讓使用者和開發人員更簡單明確地了解各個版本之間有著哪些改動。 46 | 47 | %h3#who 48 | %a.anchor{ href: "#who", aria_hidden: "true" } 49 | 哪些人需要更新日誌？ 50 | 51 | %p 52 | 大家都需要更新日誌。無論是使用者還是開發者，軟體最終的用戶都會在意軟體包含了什麼。當軟體更新了，大家會希望知道改了什麼、為什麼要改。 53 | 54 | .good-practices 55 | %h3#how 56 | %a.anchor{ href: "#how", aria_hidden: "true" } 57 | 如何寫出高品質的日誌？ 58 | 59 | %h4#principles 60 | %a.anchor{ href: "#principles", aria_hidden: "true" } 61 | 指導原則 62 | 63 | %ul 64 | %li 65 | 日誌是寫給「人」看的，不是機器。 66 | %li 67 | 每個版本都應該有獨立的進入點。 68 | %li 69 | 相同類型的改動應分組放置。 70 | %li 71 | 版本與章節應「可連結化」。 72 | %li 73 | 新版本總是寫在前面。 74 | %li 75 | 每個版本都該註記發佈日期。 76 | %li 77 | 版本命名應遵守#{link_to "語意化版本", semver}格式。 78 | 79 | %a.anchor{ href: "#types", aria_hidden: "true" } 80 | %h4#types 改動類型 81 | 82 | %ul 83 | %li 84 | %code Added 85 | 當增加了新功能。 86 | %li 87 | %code Changed 88 | 當更動了既有的功能。 89 | %li 90 | %code Deprecated 91 | 當功能將在近期被移除。 92 | %li 93 | %code Removed 94 | 當移除了現有的功能。 95 | %li 96 | %code Fixed 97 | 當修復了某些錯誤。 98 | %li 99 | %code Security 100 | 當增進了安全性漏洞。 101 | 102 | .effort 103 | 104 | %h3#effort 105 | %a.anchor{ href: "#effort", aria_hidden: "true" } 106 | 如何提升維護更新日誌的效率？ 107 | 108 | %p 109 | 在日誌上方使用 Unreleased 區塊記錄即將發佈的更新內容。 110 | 111 | %p 這麼做能夠： 112 | 113 | %ul 114 | %li 115 | 讓大家知道在未來的版本中可能會有哪些改動。 116 | %li 117 | 發佈新版本時，直接將 Unreleased 移到新版本的區塊就完成了 ヾ(*´ω｀*)ノ 118 | 119 | .bad-practices 120 | %h3#bad-practices 121 | %a.anchor{ href: "#bad-practices", aria_hidden: "true" } 122 | 難道日誌能寫得很糟嗎？ 123 | 124 | %p 當然。下面有些糟糕的範例： 125 | 126 | %h4#log-diffs 127 | %a.anchor{ href: "#log-diffs", aria_hidden: "true" } 128 | 🚫 直接使用 git log 129 | 130 | %p 131 | 使用 git log 作為更新日誌絕對不是個好主意：git log 充滿了各種無意義的訊息，像 merge commits 132 | 、亂七八糟的提交訊息、文件更新等。 133 | 134 | %p 135 | Commits 的目的應該是記錄原始碼的演化過程。有些項目會清理 commits，有些卻不會。 136 | 137 | %p 138 | 更新日誌的目的則是記錄那些值得一提的改動，經常涵蓋多個 commits，最終目的仍是讓使用者一目了然。 139 | 140 | %h4#ignoring-deprecations 141 | %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } 142 | 🚫 忽略 Deprecations 143 | 144 | %p 145 | 當使用者升級版本時，他應該要能預先知道哪些環節可能會出問題。理想的情形下，應該讓使用者有空間能預先升級即將被棄用的功能；待替換掉棄用功能之後，再升級至棄用功能被真正移除的版本。 146 | 147 | %p 148 | 即使不這麼做，也要在更新日誌中列出棄用的、移除的、或是任何可能導致程式碼失效的重大改動。 149 | 150 | %h4#confusing-dates 151 | %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } 152 | 🚫 易混淆的日期格式 153 | 154 | %p 155 | 在世界的每個角落，不同區域有著不同的時間格式，找到讓大家都滿意的日期格式不是件簡單的事。使用像 156 | 2017-07-17 的格式能清楚傳達日期、不易與其他日期格式混淆，同時也遵守 157 | #{link_to "ISO 標準", iso}，因此推薦使用像這樣的日期格式。 158 | 159 | %aside 160 | 其實還有許多應該避免的。大家可以透過 161 | = link_to "Issue", issues 162 | 或是 Pull Request 協助蒐集 ฅ' ω 'ฅ 163 | 164 | .frequently-asked-questions 165 | %h3#frequently-asked-questions 166 | %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" } 167 | 常見問題 168 | 169 | %h4#standard 170 | %a.anchor{ href: "#standard", aria_hidden: "true" } 171 | 有沒有標準格式可以參考呢？ 172 | 173 | %p 174 | 並沒有。雖然有 #{link_to "GNU 更新日誌指南", gnu_changelog_styleguide} 以及只有兩段長的 175 | #{link_to "GNU - The NEWS File 指南", gnu_the_news}（括弧笑），但這些並不足以稱為「標準」。 176 | 177 | %p 178 | 這項專案的宗旨在於提供一個 179 | #{link_to "更好的更新日誌範例", changelog}，源於觀察開源社群中優秀的實際案例，把它們蒐集在一起。 180 | 181 | %p 182 | 歡迎各位#{link_to "提供", issues}有建設性的建議和批評。 183 | 184 | %h4#filename 185 | %a.anchor{ href: "#filename", aria_hidden: "true" } 186 | 更新日誌的檔案名稱應該是？ 187 | 188 | %p 189 | 通常使用 CHANGELOG.md。也有用 190 | HISTORY、NEWS、或是 RELEASES 的例子。 191 | 192 | %p 193 | 或許你認為取什麼名字並不是件多麼重要的事，但為什麼要讓只是想看日誌的使用者不容易找到它呢？ 194 | 195 | %h4#github-releases 196 | %a.anchor{ href: "#github-releases", aria_hidden: "true" } 197 | 那麼 GitHub Releases 呢？ 198 | 199 | %p 200 | 這是個好問題。#{link_to "GitHub Releases", ghr} 201 | 能手動在簡單的 git tag（如 202 | v1.0.0） 上附加豐富的版本資訊，也能把附帶的 tag 203 | messages 轉換成漂亮的日誌格式。 204 | 205 | %p 206 | GitHub Releases 產生的日誌只能在 GitHub 上瀏覽，雖然 GitHub Releases 207 | 能做出接近本專案範例的日誌格式，但這會增加些許與 GitHub 的相依性。 208 | 209 | %p 210 | 現行的 GitHub Releases 211 | 畢竟不像典型的大寫文件（README、CONTRIBUTING 212 | 之類的），按理說會增加使用者找到的難度。另外還有個小問題，目前 GitHub 213 | Releases 頁面上並沒有提供兩版版本之間 commit logs 的連結。 214 | 215 | %h4#automatic 216 | %a.anchor{ href: "#automatic", aria_hidden: "true" } 217 | 更新日誌能被自動生成嗎？ 218 | 219 | %p 220 | 非常困難，各式各樣的提交訊息和檔案名稱難以完全掌握。 221 | 222 | %p 223 | 另外，有些開源專案使用由 #{link_to "Gemnasium", gemnasium} 224 | 團隊開發的 #{link_to "Vandamme", vandamme} 225 | 轉換更新日誌，或許可以當作參考。 226 | 227 | %h4#yanked 228 | %a.anchor{ href: "#yanked", aria_hidden: "true" } 229 | 那麼被撤下的版本呢？ 230 | 231 | %p 232 | 因為重大漏洞或安全性問題而被撤下（unpublished）的版本通常不會出現在日誌裡，但建議仍然記錄下來。你可以這樣記錄它們： 233 | 234 | %p ## 0.0.5 - 2014-12-13 [YANKED] 235 | 236 | %p 237 | 其中 [YANKED] 標記應該和原因顯眼地標示在一起，讓使用者注意到它是最重要的事。此外，用中括弧能讓轉換用的程式更容易辨認它們。 238 | 239 | %h4#rewrite 240 | %a.anchor{ href: "#rewrite", aria_hidden: "true" } 241 | 可以更改過去版本的日誌內容嗎？ 242 | 243 | %p 244 | 當然可以，總是會有好的原因來改善以往寫下的日誌。我也時常發 pull request 245 | 給更新日誌不齊全的開源專案。 246 | 247 | %p 248 | 偶爾會發現自己遺漏了某項重大更新的紀錄，很明顯你應該補齊它們。 249 | 250 | %h4#contribute 251 | %a.anchor{ href: "#contribute", aria_hidden: "true" } 252 | 我能做些什麼嗎？ 253 | 254 | %p 255 | 這份文件並不是《真理》，而是我經過深思熟慮、遵循蒐集到的資訊和範例之後提出的建議。 256 | 257 | %p 258 | 源於我期望社群能達到共識，我相信討論的過程與結果一樣重要。 259 | 260 | %p 261 | 所以，#{link_to "加入我們", gh}吧 ٩(｡・ω・｡)و 262 | 263 | .press 264 | %h3 訪談 265 | %p 266 | 我在 #{link_to "The Changelog podcast", thechangelog} 上講述了為什麼維護者與協作者應該在意更新日誌，以及建立這項專案背後的契機。 267 | -------------------------------------------------------------------------------- /config.rb: -------------------------------------------------------------------------------- 1 | # -------------------------------------- 2 | # Config 3 | # -------------------------------------- 4 | 5 | # ----- Site ----- # 6 | # Last version should be the latest English version since the manifesto is first 7 | # written in English, then translated into other languages later. 8 | $versions = (Dir.entries("source/en") - %w[. ..]) 9 | $last_version = $versions.last 10 | $previous_version = $versions[$versions.index($last_version) - 1] 11 | 12 | # This list of languages populates the language navigation. 13 | issues_url = 'https://github.com/olivierlacan/keep-a-changelog/issues' 14 | $languages = { 15 | "cs" => { 16 | name: "Čeština" 17 | }, 18 | "de" => { 19 | name: "Deutsch", 20 | notice: "Die neuste version (#{$last_version}) ist noch nicht auf Deutsch 21 | verfügbar, aber du kannst sie dir auf Englisch durchlesen 22 | und bei der Übersetzung mithelfen." 23 | }, 24 | "en" => { 25 | default: true, 26 | name: "English", 27 | new: "A new version is available" 28 | }, 29 | "es-ES" => { 30 | name: "Español", 31 | notice: "La última versión (#{$last_version}) aun no está disponible en 32 | Español, por ahora puedes leerla en Inglés y 33 | ayudar a traducirla." 34 | }, 35 | "fr" => { 36 | name: "Français", 37 | notice: "La dernière version (#{$last_version}) n'est pas encore disponible 38 | en français, mais vous pouvez la lire en anglais pour 39 | l'instant et aider à la traduire.", 40 | new: "Une nouvelle version est disponible" 41 | }, 42 | "id-ID" => { 43 | name: "Indonesia", 44 | new: "Ada versi baru tersedia" 45 | }, 46 | "it-IT" => { 47 | name: "Italiano", 48 | notice: "L'ultima versione (#{$last_version}) non è ancora disponibile in 49 | Italiano, ma la potete leggere in Inglese per ora e 50 | potete contribuire a tradurla." 51 | }, 52 | "nl" => { 53 | name: "Nederlands" 54 | }, 55 | "pl" => { 56 | name: "Polskie" 57 | }, 58 | "pt-BR" => { 59 | name: "Português do Brasil", 60 | notice: "A última versão (#{$last_version}) ainda não está disponível em 61 | Português mas nesse momento você pode lê-la em inglês e 62 | ajudar em sua tradução." 63 | }, 64 | "ru" => { 65 | name: "Pyccкий", 66 | notice: "Самая последняя версия (#{$last_version}) ещё пока не переведена на 67 | русский, но вы можете прочитать её на английском и помочь с переводом." 69 | }, 70 | "sk" => { 71 | name: "Slovenčina" 72 | }, 73 | "sl" => { 74 | name: "Slovenščina" 75 | }, 76 | "sv" => { 77 | name: "Svenska", 78 | notice: "Den senaste versionen (#{$last_version}) är ännu inte tillgänglig på Svenska, 79 | men du kan läsa det på engelska och även hjälpa till att översätta det." 81 | }, 82 | "tr-TR" => { 83 | name: "Türkçe" 84 | }, 85 | "zh-CN" => { 86 | name: "简体中文", 87 | notice: "最新版 (#{$last_version}) 暂时还没有翻译到简体中文，您可以阅读最新的英语版，并且帮助翻译，不胜感激。" 88 | }, 89 | "zh-TW" => { 90 | name: "正體中文", 91 | notice: "最新版 (#{$last_version}) 暫時還沒有翻譯到正體中文，您可以閱讀最新的英語版，並且幫助翻譯，不勝感激。" 92 | } 93 | } 94 | 95 | activate :i18n, 96 | lang_map: $languages, 97 | mount_at_root: :en 98 | 99 | set :gauges_id, '' 100 | set :publisher_url, 'https://www.facebook.com/olivier.lacan.5' 101 | set :site_url, 'http://keepachangelog.com' 102 | 103 | redirect "index.html", to: "en/#{$last_version}/index.html" 104 | 105 | $languages.each do |language| 106 | code = language.first 107 | versions = Dir.entries("source/#{code}") - %w[. ..] 108 | redirect "#{code}/index.html", to: "#{code}/#{versions.last}/index.html" 109 | end 110 | 111 | # ----- Assets ----- # 112 | 113 | set :css_dir, 'assets/stylesheets' 114 | set :js_dir, 'assets/javascripts' 115 | set :images_dir, 'assets/images' 116 | set :fonts_dir, 'assets/fonts' 117 | 118 | # ----- Images ----- # 119 | 120 | activate :automatic_image_sizes 121 | 122 | # ----- Markdown ----- # 123 | 124 | activate :syntax 125 | set :markdown_engine, :redcarpet 126 | 127 | ## Override default Redcarpet renderer in order to define a class 128 | class CustomMarkdownRenderer < Redcarpet::Render::HTML 129 | def doc_header 130 | %Q[] 131 | end 132 | 133 | def header(text, header_level) 134 | slug = text.parameterize 135 | tag_name = "h#{header_level}" 136 | anchor_link = "" 137 | header_tag_open = "<#{tag_name} id='#{slug}'>" 138 | 139 | output = "" 140 | output << header_tag_open 141 | output << anchor_link 142 | output << text 143 | output << "" 144 | 145 | output 146 | end 147 | end 148 | 149 | $markdown_config = { 150 | fenced_code_blocks: true, 151 | footnotes: true, 152 | smartypants: true, 153 | tables: true, 154 | with_toc_data: true, 155 | renderer: CustomMarkdownRenderer 156 | } 157 | set :markdown, $markdown_config 158 | 159 | # -------------------------------------- 160 | # Helpers 161 | # -------------------------------------- 162 | 163 | helpers do 164 | def path_to_url(path) 165 | Addressable::URI.join(config.site_url, path).normalize.to_s 166 | end 167 | 168 | def available_translation_for(language) 169 | language_name = language.last[:name] 170 | language_path = "source/#{language.first}" 171 | 172 | if File.exists?("#{language_path}/#{$last_version}") 173 | "#{$last_version} #{language_name}" 174 | elsif File.exists?("#{language_path}/#{$previous_version}") 175 | "#{$previous_version} #{language_name}" 176 | else 177 | nil 178 | end 179 | end 180 | end 181 | 182 | # -------------------------------------- 183 | # Content 184 | # -------------------------------------- 185 | 186 | # ----- Directories ----- # 187 | 188 | activate :directory_indexes 189 | page "/404.html", directory_index: false 190 | 191 | # -------------------------------------- 192 | # Production 193 | # -------------------------------------- 194 | 195 | # ----- Optimization ----- # 196 | 197 | configure :build do 198 | set :gauges_id, "5389808eeddd5b055a00440d" 199 | activate :asset_hash 200 | activate :gzip, {exts: %w[ 201 | .css 202 | .eot 203 | .htm 204 | .html 205 | .ico 206 | .js 207 | .json 208 | .svg 209 | .ttf 210 | .txt 211 | .woff 212 | ]} 213 | set :haml, { attr_wrapper: '"' } 214 | activate :minify_css 215 | activate :minify_html do |html| 216 | html.remove_quotes = false 217 | end 218 | activate :minify_javascript 219 | end 220 | 221 | # ----- Prefixing ----- # 222 | 223 | activate :autoprefixer do |config| 224 | config.browsers = ['last 2 versions', 'Explorer >= 10'] 225 | config.cascade = false 226 | end 227 | 228 | # Haml doesn't pick up on Markdown configuration so we have to remove the 229 | # default Markdown Haml filter and reconfigure one that follows our 230 | # global configuration. 231 | 232 | module Haml::Filters 233 | remove_filter("Markdown") #remove the existing Markdown filter 234 | 235 | module Markdown 236 | include Haml::Filters::Base 237 | 238 | def renderer 239 | $markdown_config[:renderer] 240 | end 241 | 242 | def render(text) 243 | Redcarpet::Markdown.new(renderer.new($markdown_config)).render(text) 244 | end 245 | end 246 | end 247 | -------------------------------------------------------------------------------- /source/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: Keep a Changelog 3 | title: Keep a Changelog 4 | language: en 5 | version: 0.3.0 6 | --- 7 | 8 | :markdown 9 | # Keep a CHANGELOG 10 | 11 | ## Don’t let your friends dump git logs into CHANGELOGs™ 12 | 13 | Version **#{current_page.metadata[:page][:version]}** 14 | 15 | ### What’s a change log? 16 | A change log is a file which contains a curated, chronologically ordered 17 | list of notable changes for each version of a project. 18 | 19 | %pre.changelog= File.read("CHANGELOG.md") 20 | 21 | :markdown 22 | ### What’s the point of a change log? 23 | To make it easier for users and contributors to see precisely what 24 | notable changes have been made between each release (or version) of the project. 25 | 26 | ### Why should I care? 27 | Because software tools are for people. If you don’t care, why are 28 | you contributing to open source? Surely, there must be a kernel (ha!) 29 | of care somewhere in that lovely little brain of yours. 30 | 31 | I [talked with Adam Stacoviak and Jerod Santo on The Changelog][thechangelog] 32 | (fitting, right?) podcast about why maintainers and 33 | contributors should care, and the motivations behind this project. 34 | If you can spare the time (1:06), it’s a good listen. 35 | 36 | ### What makes a good change log? 37 | I’m glad you asked. 38 | 39 | A good change log sticks to these principles: 40 | 41 | - It’s made for humans, not machines, so legibility is crucial. 42 | - Easy to link to any section (hence Markdown over plain text). 43 | - One sub-section per version. 44 | - List releases in reverse-chronological order (newest on top). 45 | - Write all dates in `YYYY-MM-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) It’s international, [sensible](http://xkcd.com/1179/), and language-independent. 46 | - Explicitly mention whether the project follows [Semantic Versioning][semver]. 47 | - Each version should: 48 | - List its release date in the above format. 49 | - Group changes to describe their impact on the project, as follows: 50 | - `Added` for new features. 51 | - `Changed` for changes in existing functionality. 52 | - `Deprecated` for once-stable features removed in upcoming releases. 53 | - `Removed` for deprecated features removed in this release. 54 | - `Fixed` for any bug fixes. 55 | - `Security` to invite users to upgrade in case of vulnerabilities. 56 | 57 | ### How can I minimize the effort required? 58 | Always have an `"Unreleased"` section at the top for keeping track of any 59 | changes. 60 | 61 | This serves two purposes: 62 | 63 | - People can see what changes they might expect in upcoming releases 64 | - At release time, you just have to change `"Unreleased"` to the version number 65 | and add a new `"Unreleased"` header at the top. 66 | 67 | ### What makes unicorns cry? 68 | Alright…let’s get into it. 69 | 70 | - **Dumping a diff of commit logs.** Just don’t do that, you’re helping nobody. 71 | - **Not emphasizing deprecations.** When people upgrade from one version to 72 | another, it should be painfully clear when something will break. 73 | - **Dates in region-specific formats.** In the U.S., people put the month first 74 | ("06-02-2012" for June 2nd, 2012, which makes *no* sense), while many people 75 | in the rest of the world write a robotic-looking "2 June 2012", yet pronounce 76 | it differently. "2012-06-02" works logically from largest to smallest, doesn't 77 | overlap in ambiguous ways with other date formats, and is an 78 | [ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Thus, it 79 | is the recommended date format for change logs. 80 | 81 | There’s more. Help me collect those unicorn tears by 82 | [opening an issue][issues] 83 | or a pull request. 84 | 85 | ### Is there a standard change log format? 86 | Sadly, no. Calm down. I know you're furiously rushing to find that link 87 | to the GNU change log style guide, or the two-paragraph GNU NEWS file 88 | "guideline". The GNU style guide is a nice start but it is sadly naive. 89 | There's nothing wrong with being naive but when people need 90 | guidance it's rarely very helpful. Especially when there are many 91 | situations and edge cases to deal with. 92 | 93 | This project [contains what I hope will become a better CHANGELOG file convention][CHANGELOG]. 94 | I don't think the status quo is good enough, and I think that as a community we 95 | can come up with better conventions if we try to extract good practices from 96 | real software projects. Please take a look around and remember that 97 | [discussions and suggestions for improvements are welcome][issues]! 98 | 99 | ### What should the change log file be named? 100 | Well, if you can’t tell from the example above, `CHANGELOG.md` is the 101 | best convention so far. 102 | 103 | Some projects also use `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, 104 | `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc. 105 | 106 | It’s a mess. All these names only makes it harder for people to find it. 107 | 108 | ### Why can’t people just use a `git log` diff? 109 | Because log diffs are full of noise — by nature. They could not make a suitable 110 | change log even in a hypothetical project run by perfect humans who never make 111 | typos, never forget to commit new files, never miss any part of a refactoring. 112 | The purpose of a commit is to document one atomic step in the process by which 113 | the code evolves from one state to another. The purpose of a change log is to 114 | document the noteworthy differences between these states. 115 | 116 | As is the difference between good comments and the code itself, 117 | so is the difference between a change log and the commit log: 118 | one describes the *why*, the other the how. 119 | 120 | ### Can change logs be automatically parsed? 121 | It’s difficult, because people follow wildly different formats and file names. 122 | 123 | [Vandamme][vandamme] is a Ruby gem 124 | created by the [Gemnasium][gemnasium] team and which parses 125 | many (but not all) open source project change logs. 126 | 127 | ### Why do you alternate between spelling it "CHANGELOG" and "change log"? 128 | "CHANGELOG" is the name of the file itself. It's a bit shouty but it's a 129 | historical convention followed by many open source projects. Other 130 | examples of similar files include [`README`][README], [`LICENSE`][LICENSE], 131 | and [`CONTRIBUTING`][CONTRIBUTING]. 132 | 133 | The uppercase naming (which in old operating systems made these files stick 134 | to the top) is used to draw attention to them. Since they're important 135 | metadata about the project, they could be useful to anyone intending to use 136 | or contribute to it, much like [open source project badges][shields]. 137 | 138 | When I refer to a "change log", I'm talking about the function of this 139 | file: to log changes. 140 | 141 | ### What about yanked releases? 142 | Yanked releases are versions that had to be pulled because of a serious 143 | bug or security issue. Often these versions don't even appear in change 144 | logs. They should. This is how you should display them: 145 | 146 | `## 0.0.5 - 2014-12-13 [YANKED]` 147 | 148 | The `[YANKED]` tag is loud for a reason. It's important for people to 149 | notice it. Since it's surrounded by brackets it's also easier to parse 150 | programmatically. 151 | 152 | ### Should you ever rewrite a change log? 153 | Sure. There are always good reasons to improve a change log. I regularly open 154 | pull requests to add missing releases to open source projects with unmaintained 155 | change logs. 156 | 157 | It's also possible you may discover that you forgot to address a breaking change 158 | in the notes for a version. It's obviously important for you to update your 159 | change log in this case. 160 | 161 | ### How can I contribute? 162 | This document is not the **truth**; it’s my carefully considered 163 | opinion, along with information and examples I gathered. 164 | Although I provide an actual [CHANGELOG][] on [the GitHub repo][gh], 165 | I have purposefully not created a proper *release* or clear list of rules 166 | to follow (as [SemVer.org][semver] does, for instance). 167 | 168 | This is because I want our community to reach a consensus. I believe the 169 | discussion is as important as the end result. 170 | 171 | So please [**pitch in**][gh]. 172 | 173 | [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md 174 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md 175 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE 176 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md 177 | [gemnasium]: https://gemnasium.com/ 178 | [gh]: https://github.com/olivierlacan/keep-a-changelog 179 | [issues]: https://github.com/olivierlacan/keep-a-changelog/issues 180 | [semver]: http://semver.org/ 181 | [shields]: http://shields.io/ 182 | [thechangelog]: http://5by5.tv/changelog/127 183 | [vandamme]: https://github.com/tech-angels/vandamme/ 184 | -------------------------------------------------------------------------------- /source/en/0.3.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: Keep a Changelog 3 | title: Keep a Changelog 4 | language: en 5 | version: 0.3.0 6 | --- 7 | 8 | :markdown 9 | # Keep a CHANGELOG 10 | 11 | ## Don’t let your friends dump git logs into CHANGELOGs™ 12 | 13 | Version **#{current_page.metadata[:page][:version]}** 14 | 15 | ### What’s a change log? 16 | A change log is a file which contains a curated, chronologically ordered 17 | list of notable changes for each version of a project. 18 | 19 | 
#{File.read("CHANGELOG.md")}
20 | 21 | ### What’s the point of a change log? 22 | To make it easier for users and contributors to see precisely what 23 | notable changes have been made between each release (or version) of the project. 24 | 25 | ### Why should I care? 26 | Because software tools are for people. If you don’t care, why are 27 | you contributing to open source? Surely, there must be a kernel (ha!) 28 | of care somewhere in that lovely little brain of yours. 29 | 30 | I [talked with Adam Stacoviak and Jerod Santo on The Changelog][thechangelog] 31 | (fitting, right?) podcast about why maintainers and 32 | contributors should care, and the motivations behind this project. 33 | If you can spare the time (1:06), it’s a good listen. 34 | 35 | ### What makes a good change log? 36 | I’m glad you asked. 37 | 38 | A good change log sticks to these principles: 39 | 40 | - It’s made for humans, not machines, so legibility is crucial. 41 | - Easy to link to any section (hence Markdown over plain text). 42 | - One sub-section per version. 43 | - List releases in reverse-chronological order (newest on top). 44 | - Write all dates in `YYYY-MM-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) It’s international, [sensible](http://xkcd.com/1179/), and language-independent. 45 | - Explicitly mention whether the project follows [Semantic Versioning][semver]. 46 | - Each version should: 47 | - List its release date in the above format. 48 | - Group changes to describe their impact on the project, as follows: 49 | - `Added` for new features. 50 | - `Changed` for changes in existing functionality. 51 | - `Deprecated` for once-stable features removed in upcoming releases. 52 | - `Removed` for deprecated features removed in this release. 53 | - `Fixed` for any bug fixes. 54 | - `Security` to invite users to upgrade in case of vulnerabilities. 55 | 56 | ### How can I minimize the effort required? 57 | Always have an `"Unreleased"` section at the top for keeping track of any 58 | changes. 59 | 60 | This serves two purposes: 61 | 62 | - People can see what changes they might expect in upcoming releases 63 | - At release time, you just have to change `"Unreleased"` to the version number 64 | and add a new `"Unreleased"` header at the top. 65 | 66 | ### What makes unicorns cry? 67 | Alright…let’s get into it. 68 | 69 | - **Dumping a diff of commit logs.** Just don’t do that, you’re helping nobody. 70 | - **Not emphasizing deprecations.** When people upgrade from one version to 71 | another, it should be painfully clear when something will break. 72 | - **Dates in region-specific formats.** In the U.S., people put the month first 73 | ("06-02-2012" for June 2nd, 2012, which makes *no* sense), while many people 74 | in the rest of the world write a robotic-looking "2 June 2012", yet pronounce 75 | it differently. "2012-06-02" works logically from largest to smallest, doesn't 76 | overlap in ambiguous ways with other date formats, and is an 77 | [ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Thus, it 78 | is the recommended date format for change logs. 79 | 80 | There’s more. Help me collect those unicorn tears by 81 | [opening an issue][issues] 82 | or a pull request. 83 | 84 | ### Is there a standard change log format? 85 | Sadly, no. Calm down. I know you're furiously rushing to find that link 86 | to the GNU change log style guide, or the two-paragraph GNU NEWS file 87 | "guideline". The GNU style guide is a nice start but it is sadly naive. 88 | There's nothing wrong with being naive but when people need 89 | guidance it's rarely very helpful. Especially when there are many 90 | situations and edge cases to deal with. 91 | 92 | This project [contains what I hope will become a better CHANGELOG file convention][CHANGELOG]. 93 | I don't think the status quo is good enough, and I think that as a community we 94 | can come up with better conventions if we try to extract good practices from 95 | real software projects. Please take a look around and remember that 96 | [discussions and suggestions for improvements are welcome][issues]! 97 | 98 | ### What should the change log file be named? 99 | Well, if you can’t tell from the example above, `CHANGELOG.md` is the 100 | best convention so far. 101 | 102 | Some projects also use `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, 103 | `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc. 104 | 105 | It’s a mess. All these names only makes it harder for people to find it. 106 | 107 | ### Why can’t people just use a `git log` diff? 108 | Because log diffs are full of noise — by nature. They could not make a suitable 109 | change log even in a hypothetical project run by perfect humans who never make 110 | typos, never forget to commit new files, never miss any part of a refactoring. 111 | The purpose of a commit is to document one atomic step in the process by which 112 | the code evolves from one state to another. The purpose of a change log is to 113 | document the noteworthy differences between these states. 114 | 115 | As is the difference between good comments and the code itself, 116 | so is the difference between a change log and the commit log: 117 | one describes the *why*, the other the how. 118 | 119 | ### Can change logs be automatically parsed? 120 | It’s difficult, because people follow wildly different formats and file names. 121 | 122 | [Vandamme][vandamme] is a Ruby gem 123 | created by the [Gemnasium][gemnasium] team and which parses 124 | many (but not all) open source project change logs. 125 | 126 | ### Why do you alternate between spelling it "CHANGELOG" and "change log"? 127 | "CHANGELOG" is the name of the file itself. It's a bit shouty but it's a 128 | historical convention followed by many open source projects. Other 129 | examples of similar files include [`README`][README], [`LICENSE`][LICENSE], 130 | and [`CONTRIBUTING`][CONTRIBUTING]. 131 | 132 | The uppercase naming (which in old operating systems made these files stick 133 | to the top) is used to draw attention to them. Since they're important 134 | metadata about the project, they could be useful to anyone intending to use 135 | or contribute to it, much like [open source project badges][shields]. 136 | 137 | When I refer to a "change log", I'm talking about the function of this 138 | file: to log changes. 139 | 140 | ### What about yanked releases? 141 | Yanked releases are versions that had to be pulled because of a serious 142 | bug or security issue. Often these versions don't even appear in change 143 | logs. They should. This is how you should display them: 144 | 145 | `## 0.0.5 - 2014-12-13 [YANKED]` 146 | 147 | The `[YANKED]` tag is loud for a reason. It's important for people to 148 | notice it. Since it's surrounded by brackets it's also easier to parse 149 | programmatically. 150 | 151 | ### Should you ever rewrite a change log? 152 | Sure. There are always good reasons to improve a change log. I regularly open 153 | pull requests to add missing releases to open source projects with unmaintained 154 | change logs. 155 | 156 | It's also possible you may discover that you forgot to address a breaking change 157 | in the notes for a version. It's obviously important for you to update your 158 | change log in this case. 159 | 160 | ### How can I contribute? 161 | This document is not the **truth**; it’s my carefully considered 162 | opinion, along with information and examples I gathered. 163 | Although I provide an actual [CHANGELOG][] on [the GitHub repo][gh], 164 | I have purposefully not created a proper *release* or clear list of rules 165 | to follow (as [SemVer.org][semver] does, for instance). 166 | 167 | This is because I want our community to reach a consensus. I believe the 168 | discussion is as important as the end result. 169 | 170 | So please [**pitch in**][gh]. 171 | 172 | [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md 173 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md 174 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE 175 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md 176 | [gemnasium]: https://gemnasium.com/ 177 | [gh]: https://github.com/olivierlacan/keep-a-changelog 178 | [issues]: https://github.com/olivierlacan/keep-a-changelog/issues 179 | [semver]: http://semver.org/ 180 | [shields]: http://shields.io/ 181 | [thechangelog]: http://5by5.tv/changelog/127 182 | [vandamme]: https://github.com/tech-angels/vandamme/ 183 | -------------------------------------------------------------------------------- /source/es-ES/0.3.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: Mantenga un Changelog 3 | title: Mantenga un Changelog 4 | language: es-ES 5 | version: 0.3.0 6 | --- 7 | 8 | :markdown 9 | # Mantener un CHANGELOG 10 | 11 | ## No dejes que tus amigos copien y peguen git logs en los CHANGELOGs™ 12 | 13 | Version **#{current_page.metadata[:page][:version]}** 14 | 15 | ### Qué es un registro de cambios (change log)? 16 | 17 | 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. 18 | 19 | 
#{File.read("CHANGELOG.md")}
20 | 21 | ### Cuál es el propósito del change log? 22 | 23 | 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. 24 | 25 | ### Por qué me debería importar? 26 | 27 | Debido a que las herramientas de software son para la gente. Si no te importa, ¿por qué contribuyes al código abierto? Sin duda, tiene que haber un "kernel" (ha!) de importancia en ese pequeño y encantador cerebro tuyo. 28 | 29 | [En el podcast "The Changelog" hablé con Adam Stacoviak y Jerod Santo][thechangelog] 30 | (muy apropiado, ¿no?) acerca de por qué nos debería importar y sobre las motivaciones que es están detrás del proyecto. Si tienes tiempo (1:06), escúchalo, vale la pena 31 | 32 | ### Cómo podemos hacer un buen change log? 33 | 34 | Me alegro de que te lo hayas preguntado. 35 | 36 | Un buen change log se guía por los siguientes principios: 37 | 38 | - Está hecho para los seres humanos, no máquinas, por lo que la legibilidad es fundamental. 39 | - Fácil de conectar a cualquier sección (de ahí a que se use Markdown sobre texto plano). 40 | - Una sub-sección por versión. 41 | - Lista los releases en un orden inversamente-cronológico (el más reciente en la parte superior). 42 | - Escribe todas las fechas en formato `AAAA-MM-DD`. (Ejemplo: `2012-06-02` en vez de `2 JUN 2012`.) Es internacional, [sensible](http://xkcd.com/1179/), e independientemente del lenguaje que usemos. 43 | - Se menciona explícitamente si el proyecto sigue la convención del [Versionamiento Semántico][semver]. 44 | - Cada versión debería: 45 | - Indicar su fecha de lanzamiento en el formato anterior. 46 | - Agrupar los cambios para describir su impacto en el proyecto, de la siguiente manera: 47 | - `Added` para funcionalidades nuevas. 48 | - `Changed` para los cambios en las funcionalidades existentes. 49 | - `Deprecated` para indicar que una característica está obsoleta y que se eliminará en las próximas versiones. 50 | - `Removed` para las características en desuso que se eliminaron en esta versión. 51 | - `Fixed` para correcciones y bugs. 52 | - `Security` para invitar a los usuarios a actualizar, en el caso de que haya vulnerabilidades. 53 | 54 | ### Cómo puedo minimizar el esfuerzo requerido? 55 | 56 | Siempre mantén una sección con el nombre `"Unreleased"` para hacer un seguimiento sobre los cambios 57 | 58 | Esto nos puede servir para dos cosas: 59 | 60 | - La gente puede ver qué cambios podrían esperar en los próximos releases 61 | - Una vez queramos hacer una release, sólo hay que cambiar `Unreleased` por el número de versión y añadir una nueva cabecera `Unreleased` en la parte superior. 62 | 63 | ### Qué es lo que hace llorar a los unicornios? 64 | 65 | Muy bien... vamos allá. 66 | 67 | - **Hacer un copia y pega de un diff o de los logs de los commits.** Simplemente no lo hagas, no estas ayudando a nadie. 68 | - **No indicar las características obsoletas.** Cuando la gente actualiza de una versión a otra,debe tener claro cuando algo se romperá. 69 | - **Fechas en formatos específicos de una región.** En los EE.UU., la gente pone primero el mes ("06/02/2012" para el 2 de junio del 2012, lo que hace no tiene sentido), mientras que muchas personas en el resto del mundo escriben de una manera muy robótica "2 JUN 2012". "2012-06-02" me parece más lógico, y también cabe comentar que es un [ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Por lo tanto, es el formato de la fecha recomendada para los change logs 70 | 71 | Pero espera! hay más ayúdame a coleccionar esas lágrimas de unicornio [abriendo una incidencia][issues] o haciendo un pull request. 72 | 73 | ### Hay algún formato estándar de formato para los change log? 74 | 75 | Tristemente, no. Pero calma. Sé que estás corriendo furiosamente intentando encontrar ese link al libro de estilo de registro de cambios de GNU, or the two-paragraph GNU NEWS file 76 | "guideline". La guía de estilo GNU es un buen comienzo, pero es tristemente cándida. No hay nada malo en ser cándida, pero cuando la gente necesita orientación es rara la vez, que resulta ser muy útil. Sobre todo, cuando hay muchas situaciones y casos muy específicos. 77 | 78 | Este proyecto [contiene lo que espero se convierta en un mejor patrón de CHANGELOGs][CHANGELOG]. 79 | 80 | No creo que la situación actual sea lo suficientemente buena, i creo que como comunidad que somos podemos llegar a mejores convenciones si tratamos de extraer buenas prácticas de proyectos de software reales. Por favor echa un pequeño vistazo y recuerda que las [sugerencias y discusiones para mejorar son bienvenidas][issues]! 81 | 82 | ### Cómo se debería llamar el change log? 83 | 84 | Bueno, si te fijas en en ejemplo anterior, `CHANGELOG.md` es la convención más usada 85 | 86 | Otros proyectos también usan los siguientes nombres `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, 87 | `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc. 88 | 89 | Es un desastre. Todos estos nombres sólo hacen más difícil la búsqueda del fichero. 90 | 91 | ### Por qué la gente no usa simplemente un `git log`? 92 | 93 | Debido a que están llenos de ruido - por naturaleza. No se podría hacer un change log adecuado ni siquiera en un proyecto hipotético dirigido por seres humanos perfectos que nunca se equivocan y que nunca se olvidan meter ningún archivo en un commit... etc. El propósito de un commit es el de documentar un cambio atómico en el cual el software evoluciona desde un estado hacia otro. El propósito del change log es el de documentar las diferencias notables entre estos estados. 94 | 95 | ### Se pueden parsear automáticamente los change logs? 96 | 97 | Es difícil, ya que la gente sigue formatos y nombres de archivo muy distintos. 98 | 99 | [Vandamme][vandamme] es un Ruby gem creado por el equipo [Gemnasium][gemnasium], que lo que hace es parsear algunos (no todos) los change logs de varios proyectos open source. 100 | 101 | ### Por que estás continuamente alternando los nombres de "CHANGELOG" a "change log"? 102 | 103 | "CHANGELOG" es el nombre del archivo en sí. Es un poco intrusivo pero es una convención histórica seguida por muchos proyectos de código abierto. Otro ejemplo de este tipo de nombres en archivos son [`README`][README], [`LICENSE`][LICENSE], 104 | y [`CONTRIBUTING`][CONTRIBUTING]. 105 | 106 | Los nombres en mayúsculas (que en algunos sistemas operativos antiguos hacían que estos ficheros aparecieran los primeros) se utilizan para llamar la atención sobre ellos. Dado que son importantes metadatos sobre el proyecto, que podría ser útil a cualquier persona con la intención de utilizar o contribuir al mismo. 107 | 108 | Cuando me refiero a "change log", estoy hablando de la función del fichero: registrar los cambios. 109 | 110 | ### Qué son las yanked releases? 111 | 112 | Las yanked releases son versiones que tuvieron que ser retiradas a causa de un grave error o problema de seguridad. A menudo, estas versiones ni siquiera aparecen en los change logs, y tendrían que aparecer. Así es como se muestran: 113 | 114 | `## 0.0.5 - 2014-12-13 [YANKED]` 115 | 116 | La sección `[YANKED]` va entre corchetes por una razón, es importante que destaque, y el echo de estar rodeado por corchetes lo hace más fácil de localizar programáticamente. 117 | 118 | ### Deberías volver a escribir un change log? 119 | 120 | Por supuesto. Siempre hay buenas razones para mejorar el change log. A veces abro "pull requests" para añadir registros faltantes en el change log de proyectos open source. 121 | 122 | ### Como puedo contribuir? 123 | 124 | Este documento no es la **verdad absoluta**; es mi cuidadosa opinión, junto con información y ejemplos que recogí. 125 | 126 | Esto es porque quiero que la comunidad llegue a un conceso. Creo que la discusión es tan importante como el resultado final. 127 | 128 | [**Contribuye**][gh]. 129 | 130 | [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md 131 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md 132 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE 133 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md 134 | [gemnasium]: https://gemnasium.com/ 135 | [gh]: https://github.com/olivierlacan/keep-a-changelog 136 | [issues]: https://github.com/olivierlacan/keep-a-changelog/issues 137 | [semver]: http://semver.org/ 138 | [shields]: http://shields.io/ 139 | [thechangelog]: http://5by5.tv/changelog/127 140 | [vandamme]: https://github.com/tech-angels/vandamme/ 141 | -------------------------------------------------------------------------------- /source/cs/0.3.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: Udržuj Changelog 3 | title: Udržuj Changelog 4 | language: cs 5 | version: 0.3.0 6 | --- 7 | 8 | :markdown 9 | # Udržuj CHANGELOG 10 | 11 | ## Nenech své kamarády házet do CHANGELOGů™ git logy. 12 | 13 | Version **#{current_page.metadata[:page][:version]}** 14 | 15 | ### Co je to changelog? 16 | Changelog je soubor, který obsahuje organizovaný, chronologicky seřazený 17 | seznam podstatných změn pro každou verzi daného projektu. 18 | 19 | 
#{File.read("CHANGELOG.md")}
20 | 21 | ### Co je smyslem changelogu? 22 | Usnadnit uživatelům a přispěvatelům přesné zobrazení podstatných změn, které 23 | byly provedeny mezi jednotlivými vydáními (verzemi) daného projektu. 24 | 25 | ### Proč by mi na tom mělo záležet? 26 | Protože softwarové nástroje jsou pro lidi. Pokud ti na tom nezáleží, tak proč 27 | přispíváš do open source projektů? Určitě musí být v tvém úžasném malém mozku 28 | alespoň jádro (haha!) ochoty. 29 | 30 | [Bavil jsem se s Adamem Stacoviakem a Jerodem Santem na podcastu The Changelog][thechangelog] 31 | (název sedí, co?) o tom proč by na tom mělo vedoucím a přispěvatelům projektů 32 | záležet a o tom jaká motivace je za tímto projektem. Jestli máš chvilku času 33 | (1:06), stojí to za poslech. 34 | 35 | ### Co dělá changelog dobrým? 36 | Výborná otázka, díky za ni. 37 | 38 | Dobrý changelog se drří těchto principů: 39 | 40 | - Je psaný pro lidi, ne pro stroje, takže čitelnost je zásadní. 41 | - Dá se v něm jednoduše odkázat na libovolnou sekci (proto raději Markdown než plain text). 42 | - Jedna pod-sekce za verzi. 43 | - Seznam vydání ve zpětně-chronologickém pořadí (nejnovější navrchu). 44 | - Psaní všech dat ve formátu `RRRR-MM-DD`. (Příklad: `2012-06-02` pro `2. červen 2012`.) Je to mezinárodní, [rozumné](http://xkcd.com/1179/) a nezávislé na jazyce. 45 | - Explicitní uvedení toho, zda projekt dodržuje [Semantické Verzování][semver]. 46 | - Každá verze by měla: 47 | - Uvádět datum vydání ve výše uvedeném formátu. 48 | - Seskupovat změny tak, aby popisovaly dopad na projekt, a to následovně: 49 | - `Added` pro nové funkce. 50 | - `Changed` pro změny v aktuálním fungování. 51 | - `Deprecated` pro dříve stabilní funkce, které budou odstraněny v novějších vydáních a nejsou podporovány. 52 | - `Removed` pro funkce odstraněné v daném vydání. 53 | - `Fixed` pro opravené chyby. 54 | - `Security` pro navržení aktualizace uživatelům v případě bezpečnostních problémů. 55 | 56 | 57 | ### Jak mohu vyžadovanou snahu snížit na minimum? 58 | Vždycky měj nahoře sekci `"Unreleased"`, ve které budou schromažďovány všechny 59 | změny. 60 | 61 | To plní hned dva účely: 62 | 63 | - Lidé uvidí, jaké změny mohou očekávat v následujících vydáních 64 | - V momentu vydání stačí změnit `"Unreleased"` na číslo verze a přidat nový nadpis `"Unreleased"` na vrch dokumentu. 65 | 66 | ### Co zaručeně rozbrečí jednorožce? 67 | Dobrá… Tak si to povíme. 68 | 69 | - **Zkopírování diffu commit logů.** To prostě nedělej, nikomu to nepomůže. 70 | - **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. 71 | - **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. 72 | 73 | To ale není všechno. Pomoz mi sbírat jednorožčí slzy tím že 74 | [otevřeš issue][issues] nebo pull request. 75 | 76 | ### Existuje pro formát changelogů nějaký standard? 77 | Bohužel ne. Klid. Vím, že se zuřivě snažíš najít ten odkaz na GNU návod jakým 78 | stylem psát changelog, nebo onen dvouodstavcový GNU NEWS soubor, který si říká 79 | "směrnice". Zmíněný GNU návod je sice hezký začátek, ale je smutně naivní. Být 80 | naivní není nic špatného, ale když lidé potřebují radu, málokdy to někomu 81 | pomůže. Obzvlášť, když existuje tolik situací a okrajových případů, se kterými 82 | se musí člověk nějak poprat. 83 | 84 | Tento projekt 85 | [obsahuje něco, co se doufám jednou stane lepší konvencí pro CHANGELOGy][CHANGELOG]. 86 | Nemyslím si, že je momentální stav dostatečně dobrý, a jsem toho názoru, že 87 | jsme jako komunita schopni vymyslet lepší konvence, pokud se budeme snažit 88 | vybrat ty nejlepší praktiky z doopravdových softwarových projektů. 89 | Porozhlédněte se a mějte na paměti, že 90 | [diskuse a návrhy na zlepšení jsou vítány][issues]! 91 | 92 | ### Jak by se měl changelog jmenovat? 93 | Inu, pokud jste to už nepoznali z příkladu výše, `CHANGELOG.md` je zatím ta 94 | nejlepší konvence. 95 | 96 | Některé projekty používají `HISTORY.txt`, `HISTORY.md`, `History.md`, 97 | `NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, 98 | `releases.md`, apod. 99 | 100 | Je v tom binec. Všecha tato jména jen komplikují život lidem, kteří se ten 101 | dokument snaží najít. 102 | 103 | ### Proč lidé jednoduše nepoužívají `git log` diff? 104 | Protože diffy logů jsou plné šumu — přirozeně. Nebyly by vyhovujícím 105 | changelogem ani v hypotetickém projektu vedeném dokonalými lidmi, kteří nikdy 106 | nedělají překlepy, nikdy nezapomínají commitnout nové soubory a nikdy jim 107 | neunikne ani ta nejmenší část refactoringu. Cílem commitu je dokumentovat 108 | jeden miniaturní krok při procesu, ve kterém se kód vyvíjí z jedné podoby do 109 | druhé. Cílem changelogu je dokumentovat podstatné změny mezi těmito podobami. 110 | 111 | Stějně jako je rozdíl mezi dobrými komentáři a samotným kódem, je také rozdíl 112 | mezi changelogem a commitlogem: jeden říká *proč* a druhý jak. 113 | 114 | ### Mohou být changelogy automaticky parsované? 115 | Je to složité, jelikož se lidé uchylují k nejrůznějším formátům a názvům 116 | souborů. 117 | 118 | [Vandamme][vandamme] je Ruby gem vytvořený týmem [Gemnasium][gemnasium], který 119 | parsuje mnoho (ale ne všechny) changelogů open source projektů. 120 | 121 | ### Proč používáš jednou "CHANGELOG" a jindy "changelog"? 122 | "CHANGELOG" je název samotného souboru. Je to třichu křiklavé, ale to už je 123 | historická konvence, kterou se řídí mnoho open source projektů. Příklady 124 | podobných souborů mohou být [`README`][README], [`LICENSE`][LICENSE] a 125 | [`CONTRIBUTING`][CONTRIBUTING]. 126 | 127 | Název psaný kapitálkami (díky kterému se ve starých operačních systémech 128 | soubory držely na nejvyšších pozicích) je používán za účelem upoutání 129 | pozornosti. Vzhledem k tomu, že se jedná o důležitá metadata o projektu a 130 | mohla by být užitečná pro kohokoliv, kdo ho chce používat nebo do něho 131 | přispívat, podobně [open source projektovým odznakům][shields]. 132 | 133 | Když mluvím o "changelogu", myslím tím funkci tohoto souboru: logování změn. 134 | 135 | ### Jak potom vypadají ta vydání, která byla zpětně stažena? 136 | Zpětně stažená vydání jsou verze, které musely být zpětně odebrány kvůli vážné 137 | chybě nebo bezpečnostním rizikům. Tyto verze se často v changelogu ani 138 | neobjevují, ale měly by. Zobrazovat by se měli takto: 139 | 140 | `## 0.0.5 - 2014-12-13 [YANKED]` 141 | 142 | Tag `[YANKED]` je naschvál křiklavý. Je důležité, aby si ho lidé všimli. Díky 143 | tomu, že je v hranatých závorkách je take jednoduší ho parsovat programem. 144 | 145 | ### Měl by se někdy changelog přepisovat? 146 | Jasně. Vždy se najde dobrý důvod pro zlepšení changelogu. Sám často otevírám 147 | pull requesty pro přidání chybějících vydání v open source projektech s 148 | neudržovanými changelogy. 149 | 150 | Je také možné, že zjistíš, že v poznámkách k verzi ve tvém projektu není 151 | zmíněna změna, která něco mohla rozbít. V tom případě jě samozřejmě důležité, 152 | aby byl changelog aktualizován. 153 | 154 | ### Jak mohu přidat ruku k dílu? 155 | Tento dokument není čistá **pravda**; je to můj názor, nad kterým jsem opatrně 156 | uvažoval, v kombinaci s informacemi a příklady, které se mi podařilo získat. 157 | I přesto, že uvádím vlastní [CHANGELOG][] v [repozitáři na GitHubu][gh], 158 | naschvál jsem nevytvořil náležité *vydání* nebo jasný seznam pravidel, kterými 159 | se někdo má řídit (jako to například udělali na [SemVer.org][semver]). 160 | 161 | Je tomu tak proto, že chci aby komunita došla ke společné shodě. Já sám jsem 162 | toho názoru, že diskuse je důležitou součástí finálního výsledku. 163 | 164 | Takže prosím [**přispějte**][gh] svou trochou do mlýna. 165 | 166 | [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md 167 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md 168 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE 169 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md 170 | [gemnasium]: https://gemnasium.com/ 171 | [gh]: https://github.com/olivierlacan/keep-a-changelog 172 | [issues]: https://github.com/olivierlacan/keep-a-changelog/issues 173 | [semver]: http://semver.org/ 174 | [shields]: http://shields.io/ 175 | [thechangelog]: http://5by5.tv/changelog/127 176 | [vandamme]: https://github.com/tech-angels/vandamme/ 177 | -------------------------------------------------------------------------------- /source/sl/0.3.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: Keep a Changelog 3 | title: Keep a Changelog 4 | language: sl 5 | version: 0.3.0 6 | --- 7 | 8 | :markdown 9 | # Vzdržujte dnevnik sprememb oz. CHANGELOG 10 | 11 | ## Ne dopustite, da vaši prijatelji odlagajo git dnevnike v CHANGELOG™ 12 | 13 | Verzija **#{current_page.metadata[:page][:version]}** 14 | 15 | ### Kaj je dnevnik sprememb? 16 | Dnevnik sprememb je datoteka, ki vsebuje kuriran, kronološko urejen 17 | seznam opaznih sprememb za vsako verzijo projekta. 18 | 19 | 
#{File.read("CHANGELOG.md")}
20 | 21 | ### Kaj je smisel dnevnika sprememb? 22 | Za poenostavitev, da uporabniki in prispevajoči sodelavci natančno vidijo, katere 23 | opazne spremembe so bile narejene med vsako izdajo (ali verzijo) projekta. 24 | 25 | ### Zakaj se truditi? 26 | Ker so programska orodja za ljudi. Če vam to ni pomembno, zakaj 27 | prispevate odprto kodnemu projektu? Zagotovo mora obstajati malenkost (hehe) 28 | skrbnosti nekje v vaši lepi glavi. 29 | 30 | Govorili smo z [Adam-om Stacoviak-om in Jerod-om Santo na temo Changelog-a][thechangelog] 31 | (ustrezno, kajne?) podcast o tem zakaj bi se morali vzdrževalci in 32 | sodelavci, ki prispevajo, truditi in o motivaciji za tem projektom. 33 | Če imate na voljo nekaj časa (1:06), je odlično poslušanje. 34 | 35 | ### Kaj naredi dnevnik sprememb odličen? 36 | Veseli me, da ste vprašali. 37 | 38 | Dober dnevnik sprememb se drži teh načel: 39 | 40 | - Je enostaven za ljudi, ne stroje, tako da je čitljivost ključnega pomena. 41 | - Enostaven za povezavo kateri koli sekciji (torej Markdown pred golim besedilom). 42 | - Ena pod-sekcija na verzijo. 43 | - Seznam izdaj v obratnem kronološkem vrstnem redu (najnovejše na vrhu). 44 | - Zapis vseh datumov v `YYYY-MM-DD` formatu. (Na primer: `2012-06-02` za `2. junij 2012`.) Je mednarnodno, [smiselno](http://xkcd.com/1179/) in neodvisno od jezika. 45 | - Eksplicitna omemba ali projekt sledi [semantičnim verzijam][semver]. 46 | - Vsaka verzija bi morala: 47 | - Imeti seznam njenih datumov izdaje v zgornjem formatu. 48 | - Skupine sprememb, ki opisujejo njihove vplive na projekt, kot sledi: 49 | - `Added` za nove lastnosti. 50 | - `Changed` za spremembe obstoječih lastnosti. 51 | - `Deprecated` za nekoč stabilne lastnosti, ki bodo odstranjene v prihajajočih verzijah. 52 | - `Removed` za zastarele lastnosti, ki so odstranjene v tej izdaji. 53 | - `Fixed` za kakršne koli popravke hroščev. 54 | - `Security` za povabilo uporabnikom, da nadgradijo v primeru varnostnih ranljivosti. 55 | 56 | ### Kako zmanjšati potreben trud? 57 | Vedno imejte `"Unreleased"` sekcijo na vrhu za sledenje katerih koli 58 | sprememb. 59 | 60 | To služi dvema namenoma: 61 | 62 | - Ljudje lahko vidijo, katere spremembe lahko pričakujejo v prihajajočih izdajah 63 | - Pri izdaji, morate tako samo spremembiti `"Unreleased"` v številko verzije 64 | in dodati nov naslov `"Unreleased"` na vrh. 65 | 66 | ### Kaj spravi samoroga v jok? 67 | Dobro … pojdimo skozi. 68 | 69 | - **Odlaganje sprememb git dnevnikov poslanih sprememb.** Temu se izogibajte, saj s tem ne pomagate nikomur. 70 | - **Nepoudarjanje zastarelosti.** Ko uporabniki nadgradijo iz ene verzije na 71 | drugo, bi moralo biti enostavno jasno, ko nekaj ne bo več delovalo. 72 | - **Datumi v lokalnih oblikah.** V ZDA, uporabniki dajo mesec na prvo mesto 73 | ("06-02-2012" za 2. junij, 2012, kar je brez smisla), medtem ko mnogi ostali 74 | uporabniki drugod po svetu pišejo "2 June 2012" robotskega izgleda, vendar 75 | izgovorijo to drugače. "2012-06-02" deluje logično po večini in se ne 76 | prekriva na dvoumne načine z ostalimi oblikami datumov. To je tudi 77 | [ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Tako je to 78 | priporočljiva oblika datuma za dnevnike sprememb. 79 | 80 | Tega je še več. Pomagajte zbrati te solze samoroga preko 81 | [odprtja težave][issues] 82 | ali zahtevka potega. 83 | 84 | ### Ali obstaja standardna oblika dnevnika sprememb? 85 | Na žalost ne. Vendar mirno kri. Vem, da besno hitite najti to povezavo 86 | v vodiču dnevnika sprememb GNU ali v datoteki dveh odstavkov "guideline" GNU 87 | NEWS. Stilski vodič GNU je lep začetek, vendar je na žalost preveč enostaven. 88 | S tem ni nič narobe, vendar ko uporabniki potrebujejo 89 | vodič, je redko v pomoč. Posebej, ko je za reševati veliko 90 | situacij in posebnih primerov. 91 | 92 | Ta projekt [vsebuje, kar upamo, da bo postalo boljša datoteka konvencij CHANGELOG][CHANGELOG]. 93 | Mislimo, da status quo ni dovolj dober in mislimo, da lahko kot skupnost 94 | naredimo boljšo konvencijo, če poskusimo izvleči dobre prakse iz 95 | realnih programskih projektov. Prosimo, poglejte naokoli in si zapomnite, da 96 | [diskusije in predlogi za izboljšave so dobrodošli][issues]! 97 | 98 | ### Kako se mora dnevnik sprememb imenovati? 99 | Če niste uspeli razbrati iz zgornjega primera, je `CHANGELOG.md` 100 | najboljša konvencija do sedaj. 101 | 102 | Nekateri projekti uporabljajo tudi `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, 103 | `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md` itd. 104 | 105 | Gre za zmešnjavo. Vsa ta imena ljudem samo otežijo najti dnevnik sprememb. 106 | 107 | ### Zakaj uporabniki ne morejo uporabiti enostavno samo `git log` sprememb? 108 | Ker so spremembe dnevnika polne šuma - privzeto. Lahko bi naredili ustrezen 109 | dnevnik sprememb tudi v hipotetičnem projektu, ki ga poganjajo popolni ljudje, ki nikoli ne naredijo 110 | napak, nikoli ne pozabijo poslati novih datotek in nikoli ne zamudijo nobenega dela refaktorizacije. 111 | Razlog pošiljke (commit-a) je dokumentirati en atomičen korak v procesu preko katerega 112 | se koda razvija iz enega stanja v drugo. Razlog dnevnika sprememb je 113 | dokumentiranje omembe vrednih sprememb med temi stanji. 114 | 115 | Kakor obstaja razlika med dobrimi komentarji in samo kodo, 116 | tako je razlika med dnevnikom sprememb in dnevnikom git commit-a: 117 | eden opisuje *zakaj*, drugi pa *kako*. 118 | 119 | ### Ali se da dnevnik sprememb samodejno razlčeniti? 120 | Je težko, ker uporabniki sledijo divje različnim formatom in imenom datotek. 121 | 122 | [Vandamme][vandamme] je Ruby gem, 123 | ki ga je ustvarila ekipa [Gemnasium][gemnasium]. Razčlenjuje 124 | mnoge (vendar ne vse) dnevnike sprememb odprto kodnih projektov. 125 | 126 | ### Zakaj razlikovanje med črkovanjem "CHANGELOG" in "change log"? 127 | "CHANGELOG" je ime same datoteke. Je nekoliko glasno, vendar je to 128 | zgodovinska konvencija, kateri sledi mnogo odprto kodnih projektov. Drugi 129 | primeri podobnih datotek vključujejo [`README`][README], [`LICENSE`][LICENSE], 130 | in [`CONTRIBUTING`][CONTRIBUTING]. 131 | 132 | Ime z velikimi črkami (kar je datoteko v starih operacijskih sistemih prikazalo na 133 | vrhu) je uporabljeno, da se povleče pozornost nanje. Ker gre za pomembne 134 | meta podatke o projektu, so lahko uporabne za kogarkoli, ki namerava uporabiti 135 | ali prispevati, precej enako kot [značke odprto kodnih projektov][shields]. 136 | 137 | Ko se sklicujemo na "change log", govorimo o funkciji te 138 | datoteke: beleženje sprememb. 139 | 140 | ### Kaj pa povlečene izdaje? 141 | T.i. yanked ali povlečene izdaje so verzije, ki so bile primorane biti potegnjene zaradi resnega 142 | hrošča ali varnostne težave. Pogostokrat se te verzije niti ne pojavijo v 143 | dnevnikih sprememb. Vendar bi se morale. Prikazane bi morale biti sledeče: 144 | 145 | `## 0.0.5 - 2014-12-13 [YANKED]` 146 | 147 | Oznaka `[YANKED]` je izpisana z velikimi črkami z razlogom. Pomembno je, da jo uporabniki 148 | opazijo. Ker je obdana z oglatimi oklepaji, jo je tudi enostavnejše razčleniti 149 | programsko. 150 | 151 | ### Ali bi morali kadarkoli prepisati dnevnik sprememb? 152 | Seveda. Vedno obstajajo dobri razlogi, kako izboljšati dnevnik sprememb. Odpiranje 153 | zahtevkov potegov je pogostokrat priporočljivo, da se doda manjkajoče izdaje 154 | odprtokodnih projektov z nevzdrževanimi dnevniki sprememb. 155 | 156 | Možno je tudi, da odkrijete, da ste pozabili nasloviti pomembne spremembe 157 | v opombah verzije. Očitno je pomembno, da vaš 158 | dnevnik sprememb v tem primeru posodobite. 159 | 160 | ### Kako lahko pomagam? 161 | Ta dokument ni **dejstvo**; je osebno temeljito premišljeno 162 | mnenje, skupaj z informacijami in primeri, ki smo jih zbrali. 163 | Čeprav ponujamo dejanski [CHANGELOG][] v [GitHub repozitoriju][gh], 164 | namenoma ni ustvarjene primerne *izdaje* ali jasnega seznama pravil 165 | za sledenje (kot ima to npr. [SemVer.org][semver]). 166 | 167 | To je zato, ker želimo, da naša skupnost doseže soglasje. Verjamemo, 168 | da je razprava tako pomembna kot končni rezultat. 169 | 170 | Torej, prosimo [**pridružite se**][gh]. 171 | 172 | [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md 173 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md 174 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE 175 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md 176 | [gemnasium]: https://gemnasium.com/ 177 | [gh]: https://github.com/olivierlacan/keep-a-changelog 178 | [issues]: https://github.com/olivierlacan/keep-a-changelog/issues 179 | [semver]: http://semver.org/ 180 | [shields]: http://shields.io/ 181 | [thechangelog]: http://5by5.tv/changelog/127 182 | [vandamme]: https://github.com/tech-angels/vandamme/ 183 | -------------------------------------------------------------------------------- /source/tr-TR/0.3.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: Değişiklik kaydı tutun 3 | title: Değişiklik kaydı tutun 4 | language: tr-TR 5 | version: 0.3.0 6 | --- 7 | 8 | :markdown 9 | # CHANGELOG dosyası kullanın 10 | 11 | ## Arkadaşlarınızın, git kayıtlarını CHANGELOG dosyalarına yığmasını engelleyin™ 12 | 13 | ### Nedir bu değişiklik kayıtları? 14 | Değişiklik kayıtları bir proje için özel olarak hazırlanmış, tarihsel sıralamayla 15 | sıralanmış, önemli değişikliklerin bir bütünüdür. 16 | 17 | 
#{File.read("CHANGELOG.md")}
18 | 19 | ### Değişikliklerin kayıtlarını tutmanın anlamı ne? 20 | Bir projenin kullanıcılarının ya da katılımcılarının, dağıtımlar (ya da sürümler) 21 | arasındaki tam olarak hangi önemli değişikliklerin olduğunu takip edebilmelerini sağlar. 22 | 23 | ### Neden umrumda olsun ki? 24 | Çünkü yazılım paketleri insanlar içindir. Eğer umrunuzda değilse neden açık kaynağa 25 | katkıda bulunuyorsunuz ki? Mutlaka sevimli beyninizin bir yerlerinde bunu önemseyen 26 | bir çekirdek (a-ha!) vardır. 27 | 28 | [Adam Stacoviak ve Jerod Santo ile Changelog Podcast'inde][thechangelog] (uyuyor, 29 | değil mi?) neden geliştiricilerin ve katılımcıların umrunda olması gerektiğini ve 30 | bu projenin arkasındaki motivasyonu konuştuk. Eğer vaktiniz varsa (1:06) iyi bir 31 | söyleşi oldu. 32 | 33 | ### Bir değişiklik kaydını iyi yapan nedir? 34 | Bunu sorduğunuza sevindim. 35 | 36 | İyi bir değişiklik kaydı şu prensiplere bağlıdır: 37 | 38 | - İnsanlar için yapılmıştır, makineler için değil, yani okunabilirliği kritiktir. 39 | - Kolayca bölümler arası bağlantı kurulabilmelidir. (Bu yüzden yalın metin yerine markdown) 40 | - Her sürüm için bir alt bölüm içermelidir. 41 | - Dağıtımları tersine tarih sırası ile listemelidir. (En yeni en üstte) 42 | - Tüm tarihler `YYYY-AA-GG` biçiminde olmalıdır. (Örneğin `2 Haziran 2012` için `2012-06-02`) Uluslararasıdır, [anlamlıdır](http://xkcd.com/1179/), ve lisan bağımsızdır. 43 | - [Anlamsal sürümleme][semver]nin desteklenip desteklenmediğini özellikle belirtilmelidir. 44 | - Her sürümde olması gerekenler: 45 | - Üstteki biçimde dağıtım tarihi. 46 | - Projeye etkileri bakımından değişikliklerin gruplanması, şöyle ki: 47 | - `Eklendi`: yeni özellikler için, 48 | - `Değişti`: var olan beceriler değiştiyse, 49 | - `Rafa kalktı`: gelecekte yok olacak var olan beceriler, 50 | - `Kaldırıldı`: bu sürümde kaldırılan, daha önce rafa kaldırılmış olan beceriler, 51 | - `Düzeltildi`: ayıklanmış hatalar, 52 | - `Güvenlik`: açıkları kapatabilmeleri için kullanıcıları bilgilendirin. 53 | 54 | ### Gerekli çabayı nasıl en aza indirebilirim? 55 | Her zaman en üstte değişiklikleri takip ettiğiniz bir `"Yayımlanmadı"` bölümü olsun. 56 | 57 | Bu, iki amaca hizmet eder: 58 | 59 | - İnsanlar gelecek sürümlerde karşılarına ne gibi değişiklikler çıkacağını görebilirler 60 | - Dağıtım zamanı geldiğinde `"Yayımlanmadı"` başlığını sürüm numarası ile değişitip 61 | tepeye yeni bir `"Yayımlanmadı"` bölümü eklemeniz yeterli. 62 | 63 | ### Tek boynuzlu atları ağlatan ne? 64 | Peki… Gelelim sadede. 65 | 66 | - **Commit kayıtlarının farkını yüklemek.** Sakın bunu yapmayın, kimseye yardım etmiyorsunuz. 67 | - **Rafa kaldırılanları ön plana çıkarmamak.** Kullanıcılar için bir sürümden diğerine 68 | yükseltme yaptıklarında neyin bozulabileceği apaçık ortada olmalı. 69 | - **Bölgesel biçimlenmiş tarihler.** ABD'de insanlar ay bilgisini önce kullanıyor 70 | ("06-02-2012" demek 2 Haziran 2012 demek yani, ki tamamen *saçma*), diğer taraftan 71 | dünyanın bir çok bölgesinde "2 Haziran 2012" gibi robotik bir yapı kullanıp farklı 72 | şekilde dile getiriyor. "2012-06-02" hem mantıksal olarak en büyüğünden en küçüğüne çalışıyor, 73 | hem de diğer tarih biçimleriyle çakışmıyor. Aynı zamanda [ISO standardında](http://www.iso.org/iso/home/standards/iso8601.htm). 74 | Bu yüzden değişiklik kayıtları için önerilen tarih biçimidir. 75 | 76 | Dahası da var. Bu tek boynuzlu at gözyaşlarını toplamak için 77 | [bir başlık açın][issues] 78 | ya da bir çekme isteği (pull request) gönderin. 79 | 80 | ### Standart bir değişiklik kaydı biçimi var mı? 81 | Ne yazık ki hayır. Sakin olun. Biliyorum, şu an alelacele GNU değişiklik kaydı 82 | stil rehberi için bağlantı arıyorsunuz, ya da iki paragraflık GNU NEWS dosyasına 83 | bakınıyorsunuz. GNU stil rehberi iyi bir başlangıç fakat üzücü derece naif. 84 | Naif olmakta yanlış bir şey yok, fakat insanlar rehberlik aradığında nadiren 85 | yardımcı oluyorlar. Özellikle ortada uğraşılacak bir çok durum ve uç örnekler 86 | mevcutken. 87 | 88 | Bu proje [umuyorum ki daha iyi CHANGELOG dosyaları için bir altyapı oluşturacak][CHANGELOG]. 89 | Mevcut durumun çok iyi olduğunu düşünmüyorum, ve topluluk olarak, gerçek yazılım 90 | projelerinden iyi pratikleri toplayarak bundan daha iyisini yapabiliriz. Lütfen 91 | etrafa bir göz gezdirin ve unutmayın [gelişme yolunda tartışmalara ve önerilere her zaman açığız][issues]! 92 | 93 | ### Değişiklik kayıtlarının dosya ismi ne olmalı? 94 | Eh, üstteki örnekten çıkartamadıysanız eğer, `CHANGELOG.md` şu ana kadarki 95 | en iyi çözüm. 96 | 97 | Bazı projeler `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, `NEWS.md`, 98 | `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md` vb de kullanıyor. 99 | 100 | Tam bir karmaşa. Tüm bu isimler insanların bu dosyayı bulmasını zorlaştırıyor. 101 | 102 | ### Neden `git log` farkları kullanılmasın? 103 | Çünkü kayıt farkları bir sürü parazit içerir - doğal olarak. Mükemmel insanlar 104 | tarafından yürütülen, hiç yazım hatasının yapılmadığı, dosyaların gönderilmesinin 105 | hiç unutulmadığı, refaktör yapılmasının atlanmadığı varsayımsal bir projede bile, 106 | uygun bir değişiklik kaydı oluşmayacaktır. Dosyaları repoya göndermenin amacı, 107 | atomik seviyede kodun bir durumdan diğerine geçişinin sağlanmasıdır. Değişiklik 108 | kayıtları ise, bu durumlar arasında önem arz eden değişiklikleri belgelemeyi 109 | amaçlıyor. 110 | 111 | İyi yorumlar ve kodun kendisi arasındaki fark, 112 | aynı şekilde değişiklik kayıtları ve commit kayıtları arasındaki gibidir: 113 | biri *neden* olduğunu, diğeri nasıl olduğunu açıklar. 114 | 115 | ### Değişiklik kayıtları otomatik olarak toplanabilir mi? 116 | Zor, çünkü insanlar bir çok farklı biçim ve dosya isimleri kullanıyorlar. 117 | 118 | [Vandamme][vandamme], [Gemnasium][gemnasium] ekibi tarafından oluşturulmuş 119 | bir Ruby Gem'idir ve bir çok (hepsini değil) açık kaynaklı projenin değişiklik 120 | kayıtlarını ayrıştırabiliyor. 121 | 122 | ### Neden arada bir "CHANGELOG" ve arada bir "değişiklik kaydı" yazıyorsun? 123 | "CHANGELOG" dosyanın ismi. Biraz fazla şaşalı ama bir çok açık kaynak kodlu 124 | proje tarafından uygulanan tarihi bir gelenek. Benzer dosyalar da var; 125 | [`README`][README], [`LICENSE`][LICENSE], ve [`CONTRIBUTING`][CONTRIBUTING]. 126 | 127 | Büyük harfle isimlendirme (eski işletim sistemlerinde dosyaların tepede 128 | gözükmelerini sağlardı) dikkat çekmek için. Proje hakkında önemli meta verileri 129 | içerdikleri için, kullanmak ya da katkıda bulunmak isteyen herkesin işine 130 | yarar, tıpkı [açık kaynaklı proje rozetleri][shields] gibi. 131 | 132 | "Değişiklik kaydı"ndan bahsettiğim zamanlar bu dosyanın işlevinden bahsediyorum: 133 | Değişiklikleri kaydetmek. 134 | 135 | ### Peki ya Geri çekilen dağıtımlar? 136 | Geri çekilen dağıtımlar, önemli hatalar ya da güvenlik sebepleri nedeniyle 137 | yayından geri çekilen sürümlerdir. Genelde bu sürümler değişiklik kayıtlarında 138 | görüntülenmezler. Görünmeliler. Tam da şu şekilde görünmeliler: 139 | 140 | `## 0.0.5 - 2014-12-13 [GERİ ÇEKİLDİ]` 141 | 142 | `[GERİ ÇEKİLDİ]` etiketi belirli bir sebepten büyük harf. İnsanların bunu fark 143 | etmeleri çok önemli. Ayrıca köşeli parantezler ile çevrelenmiş olması 144 | programatik olarak da ayrıştırılabilmesine olanak sağlıyor. 145 | 146 | ### Değişiklik kayıtlarınızı tekrar yazmalı mısınız? 147 | Tabii ki. Her zaman değişiklik kayıtlarını geliştirmek için iyi sebepler vardır. 148 | Düzenli olarak açık kaynaklı projelerde bakım yapılmayan değişiklik kayıtları 149 | için çekme istekleri yapıyorum. 150 | 151 | Ayrıca bir sürümdeki notların arasında önemli bir değişiklikten bahsetmeyi 152 | unutmuş olduğunuzu fark edebilirsiniz. Değişiklik kayıtlarınızı bu bilgi ışığında 153 | güncellemeniz gerektiği gün gibi ortada. 154 | 155 | ### Nasıl katkıda bulunabilirim? 156 | Bu belge **doğrunun kendisi** değil; benim hesaplı görüşlerimdir. Beraberinde 157 | toparlamış olduğum bilgiler ve örnekler bulunur. 158 | [GitHub repo][gh]sunda güncel bir [CHANGELOG][] sağlıyor olsam da, özellikle 159 | bir *sürüm* ya da ([SemVer.org][semver] benzeri) takip edilecek kurallar 160 | oluşturmadım. 161 | 162 | Bunu istememin sebebi topluluğun ortak bir paydada buluşmasını istememdir. 163 | İnanıyorum ki tartışmanın kendisi de sonucu kadar önemli. 164 | 165 | Yani lütfen, [**siz de katılın**][gh]. 166 | 167 | [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md 168 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md 169 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE 170 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md 171 | [gemnasium]: https://gemnasium.com/ 172 | [gh]: https://github.com/olivierlacan/keep-a-changelog 173 | [issues]: https://github.com/olivierlacan/keep-a-changelog/issues 174 | [semver]: http://semver.org/ 175 | [shields]: http://shields.io/ 176 | [thechangelog]: http://5by5.tv/changelog/127 177 | [vandamme]: https://github.com/tech-angels/vandamme/ 178 | -------------------------------------------------------------------------------- /source/sv/0.3.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: Håll en ändringslogg 3 | title: Håll en ändringslogg 4 | language: sv 5 | version: 0.3.0 6 | --- 7 | 8 | :markdown 9 | # Håll en CHANGELOG 10 | 11 | ## Låt inte dina vänner slänga in en git logs i CHANGELOG™ 12 | 13 | Version **#{current_page.metadata[:page][:version]}** 14 | 15 | ### Vad är en ändringslogg? 16 | En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad 17 | lista över ändringar för varje version av ett projekt. 18 | 19 | 
#{File.read("CHANGELOG.md")}
20 | 21 | ### Vad är meningen med en ändringslogg? 22 | För att göra det enkelt för användare och medarbetare att se exakt vilka 23 | viktiga ändringar som har gjorts mellan varje utgåva (eller version) av projektet. 24 | 25 | ### Varför ska jag bry mig? 26 | Därför att mjukvaruverktyg är för människor. Om du inte bryr dig, varför 27 | bidrar du till öppen källkod? Visst finns det väl någon del i din vackra 28 | hjärna som bryr sig. 29 | 30 | Jag [pratade med Adam Stacoviak och Jerod Santo från podcasten The Changelog][thechangelog] 31 | (passande, eller hur?) om varför ansvariga och bidragsgivare bör bry sig, 32 | och motiveringen bakom detta projekt. 33 | Om du kan avvara lite tid (1:06), rekommenderar jag att lyssna på det. 34 | 35 | ### Vad gör en bra ändringslogg? 36 | Jag är glad att du frågade. 37 | 38 | En bra ändringslogg håller sig till dessa principer: 39 | 40 | - Den är skapad för människor, inte maskiner, så läsbarhet är avgörande. 41 | - Lätt att länka till valfri sektion (därav Markdown framför klartext). 42 | - En undersektion per version. 43 | - Listar utgåvor i omvänd kronologisk ordning (nyast högst upp). 44 | - Anger alla datum på formatet `YYYY-MM-DD` 45 | (exempel: `2012-06-02` för 2:a juni 2012). Det är internationellt, 46 | [förnuftigt](http://xkcd.com/1179/) och språkoberoende. 47 | - Anger uttryckligen om projektet följer [Semantisk versionshantering][SemVer]. 48 | - Varje version bör: 49 | - Ange datum då utgåvan släpptes på formatet angivet ovan. 50 | - Gruppera ändringar för att beskriva deras inverkan på projektet enligt följande: 51 | - `Added` för nya funktioner. 52 | - `Changed` för ändringar på existerande funktionalitet. 53 | - `Deprecated` för tidigare stabila funktioner som tas bort i nästa utgåva. 54 | - `Removed` för funktioner tidigare markerade som `Deprecated` som tas bort i denna version. 55 | - `Fixed` för buggfixar. 56 | - `Security` för att uppmana användare att uppgradera vid fall av sårbarheter. 57 | 58 | ### Hur kan jag minimera den insats som krävs? 59 | Ha alltid en sektion kallad `"Unreleased"` högst upp för att hålla reda på 60 | alla ändringar. 61 | 62 | Detta tjänar två syften: 63 | 64 | - Folk kan se vilka ändringar som kan förväntas i kommande utgåvor 65 | - Vid lansering behöver du bara ändra `"Unreleased"` till versionsnumret 66 | och lägga till en ny `"Unreleased"` högst upp. 67 | 68 | ### Vad får änglarna att gråta? 69 | Okej...låt oss gå genom det. 70 | 71 | - **Dumpa ut en diff från commit-loggen.** Gör helt enkelt inte så, du hjälper ingen. 72 | - **Inte betona `deprecations`.** När användare uppgraderar från en version till 73 | en annan ska det vara smärtsamt uppenbart om något förväntas gå sönder. 74 | - **Datum i region-specifikt format.** I USA lägger folk månaden först 75 | ("06-02-2012" för 2:a juni 2012, vilket bara är *konstigt*), medan många 76 | andra runt om i världen skriver "2 June 2012" men uttalar det annorlunda. 77 | "2012-06-02" fungerar logiskt från största till minsta, inte överlappar på ett 78 | tvetydligt sätt med andra datumformat, och det är en 79 | [ISO-standard](http://www.iso.org/iso/home/standards/iso8601.htm). Dessutom 80 | är det rekommenderat datumformat för ändringsloggar. 81 | 82 | 83 | Det finns mer. Hjälp mig att samla tårarna från änglarna genom att 84 | [öppna en issue][issues] 85 | eller en pull-förfrågan. 86 | 87 | ### Finns det ett standardformat på ändringsloggar? 88 | Tyvärr inte. Men lugn. Jag vet att du frustrerad kommer att rusa iväg för att hitta 89 | den där länken till GNU:s format för ändringsloggar, eller den två stycken långa 90 | GNU NEWS-filen med "guideline". Stilguiden från GNU är en bra start, men den är 91 | tyvärr allt för naiv. Det är inget fel med att vara naiv, men när människor 92 | behöver vägledning är det inte speciellt hjälpsamt. Speciellt när det är många 93 | olika situationer och specialfall att hantera. 94 | 95 | Detta projekt [innehåller vad jag hoppas kommer att bli en bättre filkonvention 96 | för CHANGELOG][CHANGELOG]. Jag tror inte att status quo är tillräckligt bra, 97 | och jag tror att vi tillsammans kan komma fram till en bättre konvention 98 | om vi försöker att plocka ut bra erfarenheter från riktiga mjukvaruprojekt. 99 | Titta runt och kom ihåg att [diskussioner och förbättringsförslag är välkomna][issues]! 100 | 101 | ### Vad bör filen med ändringsloggen heta? 102 | Tja, om du inte kan lista ut det från exemplen ovan är `CHANGELOG.md` 103 | den bästa konvention hittills. 104 | 105 | En del projekt använder också `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, 106 | `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc. 107 | 108 | Det är en verklig röra. Alla dessa namn gör det bara svårare för människor att hitta. 109 | 110 | ### Varför kan folk inte bara använda en diff från `git log`? 111 | Eftersom logg-diffar av naturen är fulla med brus. Det kan inte ens användas 112 | för att göra en lämplig ändringslogg ens i ett hypotetiskt projekt drivet av 113 | perfekta människor som aldrig skriver fel, aldrig glömmer att checka in nya filer 114 | eller aldrig glömmer någon del av en refaktorering. Syftet med en commit är att 115 | dokumentera ett enskilt steg i processen då koden utvecklas från ett tillstånd till 116 | ett annat. Syftet med en ändringslogg är att dokumentera de anmärkningsvärda 117 | skillnaderna mellan dessa tillstånd. 118 | 119 | På samma sätt som det är skillnad mellan bra kommentarer och själva koden, 120 | är det skillnad mellan ändringsloggen och commit-loggen: 121 | en beskriver *varför* och den andra *hur*. 122 | 123 | ### Kan ändringsloggar bli automatiskt tolkade? 124 | Det är svårt då människor följer vitt olika format och filnamn. 125 | 126 | [Vandamme][vandamme] är en Ruby gem 127 | skapad av gruppen bakom [Gemnasium][gemnasium] som tolkar många (men inte alla) 128 | ändringsloggar för öppen källkod. 129 | 130 | ### Varför alternerar du mellan att skriva det som "CHANGELOG" och "ändringslogg"? 131 | "CHANGELOG" är namnet på själva filen. Det sticker ut lite, men det är en 132 | historisk konvention använt i många öppna källkodsprojekt. Andra 133 | exempel på liknande filer är [`README`][README], [`LICENSE`][LICENSE] 134 | och [`CONTRIBUTING`][CONTRIBUTING]. 135 | 136 | De stora bokstäverna i namnen (som gjorde att de i äldre operativsystem 137 | hamnade högst upp) används för att dra uppmärksamhet till dem. Då de är 138 | viktig metadata om projektet borde de vara användbara för att alla som 139 | vill använda eller bidra till det, ungefär som [open source project badges][shields]. 140 | 141 | När jag refererar till "ändringslogg" pratar jag om syftet med denna fil: 142 | att logga ändringar. 143 | 144 | ### Hur är det med brådskande utgåvor ("yanked")? 145 | Brådskande utgåvor är versioner som måste släppas p.g.a. alvarliga 146 | buggar eller säkerhetsproblem. Oftast brukar dessa versioner inte ens 147 | finnas med i ändringsloggarna. De borde det. Så här borde du visa dem: 148 | 149 | `## 0.0.5 - 2014-12-13 [YANKED]` 150 | 151 | Taggen `[YANKED]` står ut av en anledning, det är viktigt för människor 152 | att se den. Då den är omsluten med hakparenteser är det också lättare 153 | för ett program att tolka. 154 | 155 | ### Borde du någonsin förändra en ändringslogg? 156 | Självklart. Det finns alltid en bra anlending att förbättra en ändringslogg. 157 | Jag öppnar regelbundet pull requests för att lägga till saknade utgåvor 158 | för öppna källkodsprojekt som inte tar hand om sin ändringslogg. 159 | 160 | Det kan också hända att du upptäcker att du glömt att ta upp en icke 161 | bakåtkompatibel förändring i en version. I sådana fall är det självklart 162 | viktigt att uppdatera din ändringslogg. 163 | 164 | ### Hur kan jag bidra? 165 | Detta dokument är inte **sanningen**, det är en noga övervägd åsikt 166 | tillsammans med information och exempel jag har samlat på mig. 167 | Även om jag tillhandahåller en [CHANGELOG][] i min [GitHub repo][gh], 168 | har jag avsiktligt inte skapat en egentlig *utgåva* eller en tydlig lista 169 | med regler att följa (som t.ex. [SemVer.org][semver] gör). 170 | 171 | Detta beror på att jag vill att vår gemenskap ska nå samförstånd. Jag 172 | tror att diskussionen är lika viktig som slutresultatet. 173 | 174 | Så välkomna att [**diskutera**][gh]. 175 | 176 | [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md 177 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md 178 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE 179 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md 180 | [gemnasium]: https://gemnasium.com/ 181 | [gh]: https://github.com/olivierlacan/keep-a-changelog 182 | [issues]: https://github.com/olivierlacan/keep-a-changelog/issues 183 | [semver]: http://semver.org/ 184 | [shields]: http://shields.io/ 185 | [thechangelog]: http://5by5.tv/changelog/127 186 | [vandamme]: https://github.com/tech-angels/vandamme/ 187 | -------------------------------------------------------------------------------- /source/pl/0.3.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: Prowadź Changelog 3 | title: Prowadź Changelog 4 | language: pl 5 | version: 0.3.0 6 | --- 7 | 8 | :markdown 9 | # Prowadź CHANGELOG 10 | 11 | ## Nie pozwól, by twoi znajomi wklejali logi gita do CHANGELOGów™ 12 | 13 | Wersja **#{current_page.metadata[:page][:version]}** 14 | 15 | ### Czym jest changelog? 16 | Changelog, inaczej rejestr zmian lub historia zmian, to plik zawierający chronologicznie uporządkowaną listę istotnych zmian dla każdej wersji projektu. 17 | 18 | 
#{File.read("CHANGELOG.md")}
19 | 20 | ### Co jest celem prowadzenia changelogu? 21 | Changelog pomaga użytkownikom zrozumieć, jakie znaczące zmiany zostały wprowadzone w każdej wersji projektu. 22 | 23 | ### Dlaczego miałoby mi zależeć? 24 | Ponieważ narzędzia informatyczne są dla ludzi. Jeśli ci nie zależy, 25 | dlaczego przyczyniasz się do powstawania otwartego oprogramowania (open source)? 26 | 27 | Rozmawiałem na podcaście ["The Changelog" z Adamem Stacoviakiem i Jerodem Santo][thechangelog] 28 | (odpowiednia nazwa, prawda?) o tym, dlaczego osobom wspierającym otwarte programowanie powinno zależeć, 29 | oraz o celach samego projektu. Jeśli masz chwilę (1:06), zapraszam do posłuchania - warto. 30 | 31 | ### Co składa się na dobry changelog? 32 | Cieszę się, że zapytałeś. 33 | 34 | Dobry changelog trzyma się następujących zasad: 35 | 36 | - Jest stworzony dla ludzi, nie maszyn, więc liczy się czytelność. 37 | - Prostota dodawania linków do każdego rozdziału (dlatego używa się Markdown zamiast prostego tekstu). 38 | - Jeden podrozdział dla każdej wersji. 39 | - Wyszczególniaj wydania w odwrotnym porządku chronologicznym (najnowsza na górze). 40 | - 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. 41 | - Zawsze określaj, czy projekt jest zgodny z [Semantycznym Wersjonowaniem][semver]. 42 | - Każda wersja powinna: 43 | - Zawierać datę w wyżej wymienionym formacie. 44 | - Grupować zmiany w celu opisu ich wpływu na projekt, w następujący sposób: 45 | - `Added` dla nowych funkcji. 46 | - `Changed` dla zmian w istniejącej funkcjonalności. 47 | - `Deprecated` (przestarzałe) dla uprzednio stabilnych funkcji, które zostaną usunięte w przyszłych wydaniach projektu. 48 | - `Removed` dla przestarzałych funkcji usuniętych w bieżącej wersji. 49 | - `Fixed` dla poprawionych błędów (bugów). 50 | - `Security` w celu poinformowania użytkowników o zalecanej aktualizacji naprawiającej luki bezpieczeństwa. 51 | 52 | ### Jak mogę zminimalizować wysiłek wkładany w prowadzenie changelogu? 53 | Zawsze umieszczaj rozdział `"Unreleased"` na szczycie dokumentu, w celu śledzenia wszelkich zmian. 54 | 55 | Ta praktyka ma dwa cele: 56 | 57 | - Użytkownicy widzą, jakich zmian mogą się spodziewać w nadchodzących wydaniach. 58 | - W momencie aktualizacji, musisz jedynie zastąpić `"Unreleased"` wersją projektu oraz dodać nowy nagłówek `"Unreleased"` na samej górze. 59 | 60 | ### Co sprawia, że jednorożce płaczą? 61 | Dobrze... zabierzmy się za to. 62 | 63 | - **Wrzucanie logów diff z zamieszczonymi zmianami.** Po prostu tego nie rób. Nikomu tym nie pomagasz. 64 | - **Niewyszczególnianie przestarzałych funkcji.** Użytkownik powinien zostać wyraźnie poinformowany, że coś przestanie działać po aktualizacji. 65 | - **Daty w formatach regionalnych.** W USA ludzie zapisują miesiąc na samym początku daty ("06-02-2012" dla 2 czerwca 2012 r., 66 | co nie ma *najmniejszego* sensu), podczas gdy gdzie indziej wiele osób pisze "2 czerwiec 2012", jednak wymawia to w inny sposób. 67 | "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. 68 | 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. 69 | 70 | To jeszcze nie koniec. Pomóż mi zebrać wszystkie łzy jednorożców [zgłaszając problem][issues] lub wprowadzając zmianę poprzez pull request. 71 | 72 | ### Czy istnieje standardowy format changelogu? 73 | Niestety nie, ale spokojnie. Wiem, że spieszysz wkleić link do tego przewodnika stylu changelogu GNU, czy do dwóch paragrafów "wytycznych" GNU NEWS. 74 | 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. 75 | Szczególnie, gdy istnieje wiele sytuacji i szczególnych przypadków z którymi trzeba się zmierzyć. 76 | 77 | Mam nadzieję, że ten projekt zostanie uznany [lepszym standardem pliku CHANGELOG][CHANGELOG]. 78 | 79 | Nie uważam, że status quo jest wystarczające i myślę, że jako społeczność, możemy stworzyć lepsze konwencje, 80 | jeśli spróbujemy zastosować dobre praktyki stosowane w prawdziwych projektach informatycznych. 81 | Proszę, zapoznaj się z projektem i pamiętaj, że [dyskusja i sugestie są zawsze mile widziane][issues]! 82 | 83 | ### Jak powinien być nazwany plik changelog? 84 | Jeśli nie potrafisz wywnioskować z powyższego przykładu, `CHANGELOG.md` to do tej pory najlepsza konwencja. 85 | 86 | Niektóre projekty również stosują `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, 87 | `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, itd. 88 | 89 | Straszny bałagan. Wszystkie te nazwy sprawiają, że jeszcze ciężej jest odnaleźć ten plik. 90 | 91 | ### Dlaczego nie mielibyśmy po prostu stosować raportu `git log`? 92 | 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, 93 | 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. 94 | 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. 95 | 96 | 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*. 97 | 98 | ### Czy changelog może być generowany automatycznie? 99 | To nie takie proste, ponieważ ludzie stosują bardzo różne formaty oraz nazwy plików. 100 | 101 | [Vandamme][vandamme] to gem Ruby stworzony przez ekipę [Gemnasium][gemnasium], parsujący changelogi wielu (ale nie wszystkich) projektów open source. 102 | 103 | ### Dlaczego czasem stosujesz pisownię "CHANGELOG", a czasem "changelog"? 104 | "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], 105 | oraz [`CONTRIBUTING`][CONTRIBUTING]. 106 | 107 | 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. 108 | 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]. 109 | 110 | Gdy stosuję pisownię "changelog", mówię o samej funkcji tego pliku: rejestrowaniu zmian. 111 | 112 | ### A co z błędnymi wersjami (yanked)? 113 | 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. 114 | Oto jak taka wersja powinna wyglądać: 115 | 116 | `## 0.0.5 - 2014-12-13 [YANKED]` 117 | 118 | 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. 119 | 120 | ### Czy powinno się kiedykolwiek poprawiać changelog? 121 | 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. 122 | 123 | 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. 124 | Ważne jest, by zaktualizować changelog szczególnie jeśli jest to zmiana, która w istotny sposób wpływa na kompatybilność aplikacji. 125 | 126 | ### Jak mogę wnieść wkład w projekt? 127 | Ten dokument to nie jedna i jedyna **prawda**; to moja starannie sformułowana opinia wraz z informacją i przykładami które zebrałem. 128 | 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]). 129 | 130 | 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. 131 | 132 | Więc proszę, [**dołącz do projektu**][gh]. 133 | 134 | [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md 135 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md 136 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE 137 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md 138 | [gemnasium]: https://gemnasium.com/ 139 | [gh]: https://github.com/olivierlacan/keep-a-changelog 140 | [issues]: https://github.com/olivierlacan/keep-a-changelog/issues 141 | [semver]: http://semver.org/ 142 | [shields]: http://shields.io/ 143 | [thechangelog]: http://5by5.tv/changelog/127 144 | [vandamme]: https://github.com/tech-angels/vandamme/ 145 | -------------------------------------------------------------------------------- /source/it-IT/0.3.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: Keep a Changelog 3 | title: Keep a Changelog 4 | language: it-IT 5 | --- 6 | 7 | :markdown 8 | # Mantenere un CHANGELOG 9 | 10 | ## Non lasciate che i vostri amici copino e incollino i git log nei CHANGELOG ™ 11 | 12 | ### Cos'è un change log? 13 | Un change log è un file che contiene una lista curata e ordinata cronologicamente 14 | delle modifiche degne di nota per ogni versione di un progetto. 15 | 16 | 
#{File.read("CHANGELOG.md")}
17 | 18 | ### A cosa serve un change log? 19 | Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche 20 | importanti sono state fatte tra ogni release (o versione) del progetto. 21 | 22 | ### Perché dovrebbe importarmi? 23 | Perché gli strumenti software sono fatti per le persone. 24 | Se non ti importa, perché contribuisci all'open source? 25 | Di certo ci deve essere un "kernel" (ha!) di interesse 26 | da qualche parte in quel tuo amorevole cervello. 27 | 28 | [Nel podcast "The Changelog" con Adam Stacoviak e Jerod Santo][thechangelog] 29 | (titolo appropriato, vero?) ho parlato del perché maintainer e contribuenti 30 | dovrebbero esserne interessati, e delle motivazioni dietro a questo progetto. 31 | Se avete tempo (1:06), vale la pena ascoltarlo. 32 | 33 | ### Come si può fare un buon change log? 34 | Sono contento che tu l'abbia chiesto. 35 | 36 | Un buon change log è guidato dai seguenti principi: 37 | 38 | - È fatto per umani, non macchine, quindi la leggibilità è cruciale. 39 | - Facile da linkare ad altre sezioni (da cui il Markdown invece che testo normale). 40 | - Una sotto-sezione per ogni versione. 41 | - Elenca le release in ordine cronologico inverso (quelle più recenti all'inizio). 42 | - Scrive tutte le date nel formato `YYYY-MM-DD`. (Esempio: `2012-06-02` sta per `2 Giugno 2012`). È internazionale, [sensato](http://xkcd.com/1179/), e indipendente dalla lingua. 43 | - Dichiara esplicitamente se il progetto segue il [Semantic Versioning][semver]. 44 | - Ogni versione dovrebbe: 45 | - Elencare la sua data di rilascio nel formato sopra specificato. 46 | - Raggruppare le modifiche per descrivere il loro impatto sul progetto, come segue: 47 | - `Added` per le nuove funzionalità. 48 | - `Changed` per le modifiche a funzionalità esistenti. 49 | - `Deprecated` per vecchie feature stabili che verranno rimosse nelle future release. 50 | - `Removed` per funzionalità precedentemente deprecate rimosse in questa release. 51 | - `Fixed` per tutti i bug fix. 52 | - `Security` per invitare gli utilizzatori ad aggiornare in caso di vulnerabilità. 53 | 54 | ### Come posso minimizzare lo sforzo richiesto? 55 | Usa sempre una sezione `"Unreleased"` all'inizio per tenere traccia di qualsiasi modifica. 56 | 57 | Questo serve per due scopi: 58 | 59 | - La gente può vedere quali modifiche si può aspettare in future release 60 | - Ad una nuova release, si deve solo sostituire `"Unreleased"` con il numero di versione 61 | e aggiungere una nuova sezione `"Unreleased"` all'inizio. 62 | 63 | ### Cosa fa piangere gli unicorni? 64 | Bene...vediamo un po'. 65 | 66 | - **Copia&incolla un diff di commig log.** Non fatelo, così non aiutate nessuno. 67 | - **Non enfatizzare le funzioni deprecate.** Quando le persone aggiornano da una versione ad un'altra, 68 | dovrebbe essere dolorosamente chiaro quando qualcosa si romperà. 69 | - **Date in formati specifici per regione.** Negli Stati Uniti si mette prima il mese nelle date 70 | ("06-02-2012" sta per 2 Giugno 2012, che non ha senso), mentre molte persone 71 | nel resto del mondo scrivono un robotico "2 June 2012", ma lo pronunciano diversamente. 72 | "2012-06-02" funziona con la logica dal più grande al più piccolo, non ha sovrapposizioni 73 | ambigue con altri formati di date, ed è uno [standard ISO](http://www.iso.org/iso/home/standards/iso8601.htm). 74 | Per tutti questi motivi, è il formato di date raccomandato per i change log. 75 | 76 | C'è di più. Aiutatemi a collezionare queste "lacrime di unicorno" [aprendo una "issue"][issues] 77 | o una pull request. 78 | 79 | ### Esiste un formato standard per i change log? 80 | Purtroppo no. Calma. So che state furiosamente correndo a cercare quel link 81 | alla guida di stile per i change log GNU, o alle linee guida per or il file a due paragrafi GNU NEWS. 82 | La guida GNU è un buon punto di partenza, ma è tristemente ingenuo. 83 | Non c'è nulla di male nell'essere ingenuo, ma quando le persone cercano una guida, questa caratteristica 84 | è raramente d'aiuto. Specialmente se ci sono molte situazioni e casi limite da gestire. 85 | 86 | Questo progetto [contiene ciò che spero diventerà una migliore convenzione per i file CHANGELOG][CHANGELOG]. 87 | Non credo che lo status quo sia sufficientemente buono, e penso che noi, come comunità, 88 | possiamo arrivare a convenzioni migliori se tentiamo di estrarre le pratiche migliori 89 | da progetti software reali. Vi consiglio di guardarvi intorno e ricordare che 90 | [ogni discussione e suggerimento per migliorare sono sempre benvenuti][issues]! 91 | 92 | ### Come si dovrebbe chiamare il file contenente il change log? 93 | Se non l'avete dedotto dall'esempio qui sopra, `CHANGELOG.md` è la convenzione migliore finora. 94 | 95 | Alcuni progetti usano anche `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, 96 | `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc. 97 | 98 | È un disastro. Tutti questi nomi contribuiscono solo a rendere più difficile trovarlo. 99 | 100 | ### Perché la gente non si limita ad usare diff di `git log`? 101 | Perché i log diff sono pieni di rumore, per loro natura. Non potrebbero creare un change log 102 | decente nemmeno in un ipotetico progetto gestito da perfetti umani che non fanno mai errori 103 | di digitazione, non dimenticano mai di fare commit dei nuovi file, non dimenticano mai 104 | alcuna parte di un refactoring. 105 | Lo scopo di un commit è di documentare un passo atomico nel processo di evoluzione del codice 106 | da uno stato ad un altro. Lo scopo di un change log è di documentare le differenze 107 | degne di nota tra questi stati. 108 | 109 | La differenza tra un change log e un commit log è 110 | come la differenza tra un buon commento nel codice e il codice stesso: 111 | uno descrive il *perché*, l'altro il come. 112 | 113 | ### Si possono analizzare automaticamente i change log? 114 | È difficile, perché le persone usano formati e nomi di file profondamente diversi. 115 | 116 | [Vandamme][vandamme] è una Ruby gem 117 | creata dal team [Gemnasium][gemnasium] ed è in grado di fare il parsing dei 118 | change log di molti (ma non tutti) i progetti open source. 119 | 120 | ### Perché si alterna tra i nomi "CHANGELOG" e "change log"? 121 | "CHANGELOG" è il nome del file. È un po' invadente ma è una 122 | convenzione storica seguita da molti progetti open source. 123 | Altri esempi di file simili includono [`README`][README], [`LICENSE`][LICENSE], 124 | e [`CONTRIBUTING`][CONTRIBUTING]. 125 | 126 | I nomi in maiuscolo (che su vecchi sistemi operativi erano ordinati per primi) 127 | vengono usati per attirare l'attenzione su di essi. Poiché sono metadati 128 | importanti relativi al progetto, possono essere utili per chiunque voglia usarlo 129 | o contribuire ad esso, un po' come i [badge dei progetti open source][shields]. 130 | 131 | Quando mi riferisco a un "change log", sto parlando della funzione di questo file: 132 | registrare le modifiche. 133 | 134 | ### Cosa sono le release "yanked"? 135 | Le release "yanked" sono versioni che sono state rimosse a causa di bug seri 136 | o problemi di sicurezza. Spesso queste versioni non appaiono nei change 137 | log. Invece dovrebbero esserci, nel seguente modo: 138 | 139 | `## 0.0.5 - 2014-12-13 [YANKED]` 140 | 141 | L'etichetta `[YANKED]` è in maiuscolo per un motivo. È importante che la gente la noti. 142 | Poiché è racchiusa tra parentesi quadre è anche più semplice da riconoscere nel parsing automatizzato. 143 | 144 | ### Si dovrebbe mai modificare un change log? 145 | Certo. Ci sono sempre buoni motivi per migliorare un change log. Io apro regolarmente 146 | delle pull request per aggiungere release mancanti ai progetti open source che non mantengono 147 | correttamente i change log. 148 | 149 | È anche possibile che si scopra di aver dimenticato di annotare una modifica 150 | non retro-compatibile nelle note per una versione. Ovviamente è importante aggiornare 151 | il change log in questo caso. 152 | 153 | ### Come posso contribuire? 154 | Questo documento non è la **verità assoluta**; è solo la mia attenta 155 | opinione, arricchita dalle informazioni ed esempi che ho raccolto. 156 | Anche se fornisco un [CHANGELOG][] reale sul [repository GitHub][gh], 157 | ho volutamente evitato di creare una *release* o una chiara lista di regole 158 | da seguire (come fa, ad esempio, [SemVer.org][semver]). 159 | 160 | Questo è perché voglio che la nostra comunità raggiunga un consenso. Credo che 161 | la discussione sia importante almeno quanto il risultato finale. 162 | 163 | Quindi per favore [**partecipate**][gh]. 164 | 165 | [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md 166 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md 167 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE 168 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md 169 | [gemnasium]: https://gemnasium.com/ 170 | [gh]: https://github.com/olivierlacan/keep-a-changelog 171 | [issues]: https://github.com/olivierlacan/keep-a-changelog/issues 172 | [semver]: http://semver.org/ 173 | [shields]: http://shields.io/ 174 | [thechangelog]: http://5by5.tv/changelog/127 175 | [vandamme]: https://github.com/tech-angels/vandamme/ 176 | -------------------------------------------------------------------------------- /source/assets/stylesheets/normalize.css: -------------------------------------------------------------------------------- 1 | /*! normalize.css v3.0.1 | MIT License | git.io/normalize */ 2 | 3 | /** 4 | * 1. Set default font family to sans-serif. 5 | * 2. Prevent iOS text size adjust after orientation change, without disabling 6 | * user zoom. 7 | */ 8 | 9 | html { 10 | font-family: sans-serif; /* 1 */ 11 | -ms-text-size-adjust: 100%; /* 2 */ 12 | -webkit-text-size-adjust: 100%; /* 2 */ 13 | } 14 | 15 | /** 16 | * Remove default margin. 17 | */ 18 | 19 | body { 20 | margin: 0; 21 | } 22 | 23 | /* HTML5 display definitions 24 | ========================================================================== */ 25 | 26 | /** 27 | * Correct `block` display not defined for any HTML5 element in IE 8/9. 28 | * Correct `block` display not defined for `details` or `summary` in IE 10/11 and Firefox. 29 | * Correct `block` display not defined for `main` in IE 11. 30 | */ 31 | 32 | article, 33 | aside, 34 | details, 35 | figcaption, 36 | figure, 37 | footer, 38 | header, 39 | hgroup, 40 | main, 41 | nav, 42 | section, 43 | summary { 44 | display: block; 45 | } 46 | 47 | /** 48 | * 1. Correct `inline-block` display not defined in IE 8/9. 49 | * 2. Normalize vertical alignment of `progress` in Chrome, Firefox, and Opera. 50 | */ 51 | 52 | audio, 53 | canvas, 54 | progress, 55 | video { 56 | display: inline-block; /* 1 */ 57 | vertical-align: baseline; /* 2 */ 58 | } 59 | 60 | /** 61 | * Prevent modern browsers from displaying `audio` without controls. 62 | * Remove excess height in iOS 5 devices. 63 | */ 64 | 65 | audio:not([controls]) { 66 | display: none; 67 | height: 0; 68 | } 69 | 70 | /** 71 | * Address `[hidden]` styling not present in IE 8/9/10. 72 | * Hide the `template` element in IE 8/9/11, Safari, and Firefox < 22. 73 | */ 74 | 75 | [hidden], 76 | template { 77 | display: none; 78 | } 79 | 80 | /* Links 81 | ========================================================================== */ 82 | 83 | /** 84 | * Remove the gray background color from active links in IE 10. 85 | */ 86 | 87 | a { 88 | background: transparent; 89 | } 90 | 91 | /** 92 | * Improve readability when focused and also mouse hovered in all browsers. 93 | */ 94 | 95 | a:active, 96 | a:hover { 97 | outline: 0; 98 | } 99 | 100 | /* Text-level semantics 101 | ========================================================================== */ 102 | 103 | /** 104 | * Address styling not present in IE 8/9/10/11, Safari, and Chrome. 105 | */ 106 | 107 | abbr[title] { 108 | border-bottom: 1px dotted; 109 | } 110 | 111 | /** 112 | * Address style set to `bolder` in Firefox 4+, Safari, and Chrome. 113 | */ 114 | 115 | b, 116 | strong { 117 | font-weight: bold; 118 | } 119 | 120 | /** 121 | * Address styling not present in Safari and Chrome. 122 | */ 123 | 124 | dfn { 125 | font-style: italic; 126 | } 127 | 128 | /** 129 | * Address variable `h1` font-size and margin within `section` and `article` 130 | * contexts in Firefox 4+, Safari, and Chrome. 131 | */ 132 | 133 | h1 { 134 | font-size: 2em; 135 | margin: 0.67em 0; 136 | } 137 | 138 | /** 139 | * Address styling not present in IE 8/9. 140 | */ 141 | 142 | mark { 143 | background: #ff0; 144 | color: #000; 145 | } 146 | 147 | /** 148 | * Address inconsistent and variable font size in all browsers. 149 | */ 150 | 151 | small { 152 | font-size: 80%; 153 | } 154 | 155 | /** 156 | * Prevent `sub` and `sup` affecting `line-height` in all browsers. 157 | */ 158 | 159 | sub, 160 | sup { 161 | font-size: 75%; 162 | line-height: 0; 163 | position: relative; 164 | vertical-align: baseline; 165 | } 166 | 167 | sup { 168 | top: -0.5em; 169 | } 170 | 171 | sub { 172 | bottom: -0.25em; 173 | } 174 | 175 | /* Embedded content 176 | ========================================================================== */ 177 | 178 | /** 179 | * Remove border when inside `a` element in IE 8/9/10. 180 | */ 181 | 182 | img { 183 | border: 0; 184 | } 185 | 186 | /** 187 | * Correct overflow not hidden in IE 9/10/11. 188 | */ 189 | 190 | svg:not(:root) { 191 | overflow: hidden; 192 | } 193 | 194 | /* Grouping content 195 | ========================================================================== */ 196 | 197 | /** 198 | * Address margin not present in IE 8/9 and Safari. 199 | */ 200 | 201 | figure { 202 | margin: 1em 40px; 203 | } 204 | 205 | /** 206 | * Address differences between Firefox and other browsers. 207 | */ 208 | 209 | hr { 210 | -moz-box-sizing: content-box; 211 | box-sizing: content-box; 212 | height: 0; 213 | } 214 | 215 | /** 216 | * Contain overflow in all browsers. 217 | */ 218 | 219 | pre { 220 | overflow: auto; 221 | } 222 | 223 | /** 224 | * Address odd `em`-unit font size rendering in all browsers. 225 | */ 226 | 227 | code, 228 | kbd, 229 | pre, 230 | samp { 231 | font-family: monospace, monospace; 232 | font-size: 1em; 233 | } 234 | 235 | /* Forms 236 | ========================================================================== */ 237 | 238 | /** 239 | * Known limitation: by default, Chrome and Safari on OS X allow very limited 240 | * styling of `select`, unless a `border` property is set. 241 | */ 242 | 243 | /** 244 | * 1. Correct color not being inherited. 245 | * Known issue: affects color of disabled elements. 246 | * 2. Correct font properties not being inherited. 247 | * 3. Address margins set differently in Firefox 4+, Safari, and Chrome. 248 | */ 249 | 250 | button, 251 | input, 252 | optgroup, 253 | select, 254 | textarea { 255 | color: inherit; /* 1 */ 256 | font: inherit; /* 2 */ 257 | margin: 0; /* 3 */ 258 | } 259 | 260 | /** 261 | * Address `overflow` set to `hidden` in IE 8/9/10/11. 262 | */ 263 | 264 | button { 265 | overflow: visible; 266 | } 267 | 268 | /** 269 | * Address inconsistent `text-transform` inheritance for `button` and `select`. 270 | * All other form control elements do not inherit `text-transform` values. 271 | * Correct `button` style inheritance in Firefox, IE 8/9/10/11, and Opera. 272 | * Correct `select` style inheritance in Firefox. 273 | */ 274 | 275 | button, 276 | select { 277 | text-transform: none; 278 | } 279 | 280 | /** 281 | * 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio` 282 | * and `video` controls. 283 | * 2. Correct inability to style clickable `input` types in iOS. 284 | * 3. Improve usability and consistency of cursor style between image-type 285 | * `input` and others. 286 | */ 287 | 288 | button, 289 | html input[type="button"], /* 1 */ 290 | input[type="reset"], 291 | input[type="submit"] { 292 | -webkit-appearance: button; /* 2 */ 293 | cursor: pointer; /* 3 */ 294 | } 295 | 296 | /** 297 | * Re-set default cursor for disabled elements. 298 | */ 299 | 300 | button[disabled], 301 | html input[disabled] { 302 | cursor: default; 303 | } 304 | 305 | /** 306 | * Remove inner padding and border in Firefox 4+. 307 | */ 308 | 309 | button::-moz-focus-inner, 310 | input::-moz-focus-inner { 311 | border: 0; 312 | padding: 0; 313 | } 314 | 315 | /** 316 | * Address Firefox 4+ setting `line-height` on `input` using `!important` in 317 | * the UA stylesheet. 318 | */ 319 | 320 | input { 321 | line-height: normal; 322 | } 323 | 324 | /** 325 | * It's recommended that you don't attempt to style these elements. 326 | * Firefox's implementation doesn't respect box-sizing, padding, or width. 327 | * 328 | * 1. Address box sizing set to `content-box` in IE 8/9/10. 329 | * 2. Remove excess padding in IE 8/9/10. 330 | */ 331 | 332 | input[type="checkbox"], 333 | input[type="radio"] { 334 | box-sizing: border-box; /* 1 */ 335 | padding: 0; /* 2 */ 336 | } 337 | 338 | /** 339 | * Fix the cursor style for Chrome's increment/decrement buttons. For certain 340 | * `font-size` values of the `input`, it causes the cursor style of the 341 | * decrement button to change from `default` to `text`. 342 | */ 343 | 344 | input[type="number"]::-webkit-inner-spin-button, 345 | input[type="number"]::-webkit-outer-spin-button { 346 | height: auto; 347 | } 348 | 349 | /** 350 | * 1. Address `appearance` set to `searchfield` in Safari and Chrome. 351 | * 2. Address `box-sizing` set to `border-box` in Safari and Chrome 352 | * (include `-moz` to future-proof). 353 | */ 354 | 355 | input[type="search"] { 356 | -webkit-appearance: textfield; /* 1 */ 357 | -moz-box-sizing: content-box; 358 | -webkit-box-sizing: content-box; /* 2 */ 359 | box-sizing: content-box; 360 | } 361 | 362 | /** 363 | * Remove inner padding and search cancel button in Safari and Chrome on OS X. 364 | * Safari (but not Chrome) clips the cancel button when the search input has 365 | * padding (and `textfield` appearance). 366 | */ 367 | 368 | input[type="search"]::-webkit-search-cancel-button, 369 | input[type="search"]::-webkit-search-decoration { 370 | -webkit-appearance: none; 371 | } 372 | 373 | /** 374 | * Define consistent border, margin, and padding. 375 | */ 376 | 377 | fieldset { 378 | border: 1px solid #c0c0c0; 379 | margin: 0 2px; 380 | padding: 0.35em 0.625em 0.75em; 381 | } 382 | 383 | /** 384 | * 1. Correct `color` not being inherited in IE 8/9/10/11. 385 | * 2. Remove padding so people aren't caught out if they zero out fieldsets. 386 | */ 387 | 388 | legend { 389 | border: 0; /* 1 */ 390 | padding: 0; /* 2 */ 391 | } 392 | 393 | /** 394 | * Remove default vertical scrollbar in IE 8/9/10/11. 395 | */ 396 | 397 | textarea { 398 | overflow: auto; 399 | } 400 | 401 | /** 402 | * Don't inherit the `font-weight` (applied by a rule above). 403 | * NOTE: the default cannot safely be changed in Chrome and Safari on OS X. 404 | */ 405 | 406 | optgroup { 407 | font-weight: bold; 408 | } 409 | 410 | /* Tables 411 | ========================================================================== */ 412 | 413 | /** 414 | * Remove most spacing between table cells. 415 | */ 416 | 417 | table { 418 | border-collapse: collapse; 419 | border-spacing: 0; 420 | } 421 | 422 | td, 423 | th { 424 | padding: 0; 425 | } 426 | -------------------------------------------------------------------------------- /source/ru/0.3.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: Ведите Changelog 3 | title: Ведите Changelog 4 | language: ru 5 | version: 0.3.0 6 | --- 7 | 8 | :markdown 9 | # Ведите CHANGELOG 10 | 11 | ## Не позволяйте друзьям сливать логи гита в CHANGELOG™ 12 | 13 | Version **#{current_page.metadata[:page][:version]}** 14 | 15 | ### Что такое лог изменений? 16 | 17 | Лог изменений – это файл, который содержит поддерживаемый, упорядоченный в 18 | хронологическом порядке список значимых изменений для каждой версии проекта с 19 | открытым исходным кодом. 20 | 21 | 
#{File.read("CHANGELOG.md")}
22 | 23 | ### Для чего нужен лог изменений? 24 | 25 | Чтобы пользователи и контрибьюторы могли с меньшими усилиями точно 26 | определить, какие значимые изменения были сделаны в каждом релизе (или 27 | версии) проекта. 28 | 29 | ### Почему я вообще должен думать об этом? 30 | 31 | Потому, что инструменты программирования делаются для людей. Если вам пофигу, 32 | зачем вы вообще занимаетесь программным обеспечением с открытым исходным 33 | кодом? У вас обязательно в голове должен быть центр «не пофигу» :) 34 | 35 | Я [беседовал с Адамом Стаковиаком и с Джеродом Санто в подкасте The 36 | Changelog][thechangelog] (в тему название, правда?) о том почему авторам 37 | программного обеспечения с открытым исходным кодом и их коллегам должно быть 38 | не пофигу, и о моих мотивах в создании этого проекта. Послушайте, если у вас 39 | есть время (1:06). 40 | 41 | ### Что должно быть в хорошем логе изменений? 42 | 43 | Я рад, что вы спросили. 44 | 45 | Хороший лог изменений придерживается этих приниципов: 46 | 47 | - Он сделан для людей, а не машин, так что понятность имеет решающее 48 | значение. 49 | - Легко сослаться на любой раздел (поэтому Markdown лучше обычного текста). 50 | - Один подраздел на каждую версию. 51 | - Релизы перечислены в обратном хронологическом порядке (самые новые – 52 | сверху). 53 | - Пишите все даты в формате `YYYY-MM-DD`. (Например: `2012-06-02` для даты `2 54 | июня 2012`.) Он международный, [рациональный](http://xkcd.com/1179/), и 55 | независим от языка. 56 | - Ясно указывает, использует ли проект [Семантическое 57 | Версионирование][semver]. 58 | - Каждая версия должна: 59 | - Показывать дату релиза в формате, упомянутом выше. 60 | - Группировать изменения согласно их влиянию на проект следующим образом: 61 | - `Added` для новых функций. 62 | - `Changed` для изменений в существующей функциональности. 63 | - `Deprecated` для функциональности, которая будет удалена в следующих 64 | версиях. 65 | - `Removed` для функциональности, которая удалена в этой версии. 66 | - `Fixed` для любых исправлений. 67 | - `Security` для обновлений безопасности. 68 | 69 | ### Как минимизировать время, необходимое для ведения лога изменений? 70 | 71 | Всегда ведите секцию `Unreleased` в начале файла, чтобы держать в ней не 72 | выпущенные изменения. 73 | 74 | Это нужно для двух вещей: 75 | 76 | - Люди смогут видеть, какие изменения ожидаются в ближайших релизах 77 | - В момент релиза вам нужно всего лишь заменить секцию `Unreleased` на номер 78 | версии и добавить новую секцию `Unreleased` в начале файла. 79 | 80 | ### Что заставляет плакать единорогов? 81 | 82 | Хорошо… давайте разберёмся. 83 | 84 | - **Выгрузка изменений лога коммитов.** Просто не делайте так, это никому не 85 | принесёт пользы. 86 | - **Отсутствие отметок планируемой к удалению функциональности.** Когда люди 87 | обновляются от одной версии к другой, им должно быть очевидно до боли, что 88 | сломается. 89 | - **Даты в местном формате.** В Соединённых Штатах, люди сначала пишут месяц 90 | («06-02-2012» для даты 2 июня 2012, что не имеет *никакого* смысла), хотя 91 | много людей в остальном мире пишет роботоподобное «2 июня 2012», всё ещё 92 | произнося это по-другому. «2012-06-02» логично работает от самого большого 93 | к самому маленькому, не пересекается с другими форматами дат, и является 94 | [стандартом ISO](http://www.iso.org/iso/home/standards/iso8601.htm). Таким 95 | образом, этот формат является рекомендуемым для логов изменений. 96 | 97 | Существуют и другие. Помогите мне собрать слёзы единорогов, 98 | [открыв тикет][issues] или пулл-реквест. 99 | 100 | ### Существует стандарт формата лога изменений? 101 | 102 | К сожалению, нет. Спокойней. Я знаю, что вы яростно бросились на поиски 103 | ссылки на GNU-руководства по стилю лога изменений, или на поиски файла 104 | «guideline» с парой параграфов в GNU NEWS. GNU-руководство по стилю неплохо 105 | для начала, но оно наивно. В наивности нет ничего плохого, но когда людям 106 | нужно руководство, она редко бывает полезна. Особенно, когда приходиться 107 | сталкиваться со множеством краевых случаев. 108 | 109 | Этот проект [содержит информацию, которая, я надеюсь, станет соглашением 110 | получше о ведении файлов CHANGELOG][CHANGELOG] для всех проектов с открытым 111 | исходным кодом. Может ли сообщество учиться на своих ошибках, а не просто 112 | действовать согласно десяти записям, которые были написаны много лет назал, 113 | и, якобы, без одной ошибки? Хорошо. Поэтому, пожалуйста, посмотрите вокруг, и 114 | помните, что [обсуждения и предложения по улучшению приветствуются][issues]! 115 | 116 | ### Как можно назвать файл лога изменений? 117 | 118 | Ну, если вы не не можете ответить на этот вопрос, глядя на пример выше, 119 | `CHANGELOG.md` пока наилучший вариант. 120 | 121 | Некоторые проекты используют `HISTORY.txt`, `HISTORY.md`, `History.md`, 122 | `NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, 123 | `releases.md`, и так далее. 124 | 125 | Это непорядок. Все эти имена только усложняют поиск нужного файла. 126 | 127 | ### Почему люди не могут использовать просто дифф команды `git log`? 128 | 129 | Потому, что диффы логов по своей природе содержат слишком много «шума». С их 130 | помощью невозможно сделать подходящий лог изменений даже в гипотетическом 131 | проекте, который делается идеальными программистами, которые никогда не 132 | делают опечаток, никогда не забывают коммитить новые файлы, никогда не 133 | пропускают ни одну часть рефакторинга. Назначение коммита в том, чтобы 134 | задокументировать один атомарный шаг в процессе развития кода от одного 135 | состояния к другому. Назначение лога изменений – документировать значимые 136 | различия между этими состояниями. 137 | 138 | Как отличаются хорошие комментарии к коду и сам код, также отличаются друг от 139 | друга и лог изменений с логом коммитов: первые отвечают на вопрос 140 | *почему*, а вторые на вопрос как. 141 | 142 | ### Могут ли логи изменений быть автоматически распарсены? 143 | 144 | Это сложно из-за того, что люди следуют сильно отличающимся форматам и 145 | соглашениям о именах файлов. 146 | 147 | Гем для Руби [Vandamme][vandamme], который создали в команде 148 | [Gemnasium][gemnasium], парсит многие (но не все) логи изменений проектов с 149 | открытым исходным кодом. 150 | 151 | ### Почему вы пишите то «CHANGELOG», то «лог изменений»? 152 | 153 | «CHANGELOG» – это имя файла. Оно несколько крикливо, но это историческое 154 | соглашение, которому следуют многие проекты с открытым исходным кодом. В 155 | качестве примеров подобных файлов можно привести [`README`][README], 156 | [`LICENSE`][LICENSE], и [`CONTRIBUTING`][CONTRIBUTING]. 157 | 158 | Верхний регистр в имени файла (который в старых операционных системах 159 | заставляет эти файлы находиться наверху списков) используется для привлечения 160 | внимания. Так как в этих файлах содержится важная метаинформация о проекте, 161 | они могут быть полезны любому использующему или дорабатывющему проект, также 162 | как [бейджи проектов с открытым исходным кодом][shields]. 163 | 164 | Когда я упоминаю «лог изменений», я говорою о назначении этого файла: об 165 | учёте изменений. 166 | 167 | ### Как насчёт yanked-релизов? 168 | 169 | Yanked-релизы – это версии, которые изымаются из обращения из-за серьёзного 170 | бага или проблемы безопасности в них. Часто такие версии даже не упоминаются 171 | в логах изменений. А должны. И вот как вам следует их упоминать: 172 | 173 | `## 0.0.5 - 2014-12-13 [YANKED]` 174 | 175 | Тег `[YANKED]` такой «громкий» не просто так. Очень важно, чтобы люди его 176 | заметили. А из-за того, что он окружён скобками, его легче определить 177 | программно. 178 | 179 | ### Стоит ли переписывать лог изменений? 180 | 181 | Конечно. Всегда есть причины для улучшения лога изменений. Я регулярно 182 | открываю пулл-реквесты в проекты с открытым исходным кодом с 183 | неподдерживаемыми логами изменений для добавления недостающих релизов. 184 | 185 | Также вы можете обнаружить что вы забыли адресовать критичное изменение в 186 | описании версии. В этом случае очевидно, что нужно обновить лог 187 | изменений. 188 | 189 | ### Как я могу помочь? 190 | 191 | Этот документ **не истина в последней инстанции**; это моё тщательно 192 | сформулированное мнение вместе с информацией и примерами, которые я собрал. 193 | Хотя я предоставил настоящий [CHANGELOG][] из [GitHub-репозитария][gh], я 194 | специально избегал цели создать *стандарт* или чёткий список правил (как это 195 | делает, например, [SemVer.org][semver]). 196 | 197 | Я сделал это потому, что хочу, чтобы наше сообщество достигло консенсуса. Я 198 | верю, что дискуссия также важна, как и её результат. 199 | 200 | Так что, пожалуйста, [**участвуйте**][gh]. 201 | 202 | [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md 203 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md 204 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE 205 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md 206 | [gemnasium]: https://gemnasium.com/ 207 | [gh]: https://github.com/olivierlacan/keep-a-changelog 208 | [issues]: https://github.com/olivierlacan/keep-a-changelog/issues 209 | [semver]: http://semver.org/ 210 | [shields]: http://shields.io/ 211 | [thechangelog]: http://5by5.tv/changelog/127 212 | [vandamme]: https://github.com/tech-angels/vandamme/ 213 | -------------------------------------------------------------------------------- /source/pt-BR/0.3.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: Mantenha um CHANGELOG 3 | title: Mantenha um CHANGELOG 4 | language: pt-BR 5 | version: 0.3.0 6 | --- 7 | 8 | :markdown 9 | # Mantenha um CHANGELOG 10 | 11 | ## Não deixe seus amigos despejarem logs de commits em CHANGELOGs™ 12 | 13 | Version **#{current_page.metadata[:page][:version]}** 14 | 15 | ### O que é um *changelog*? 16 | 17 | Um *changelog* é um arquivo que contém uma lista selecionada, ordenada 18 | cronologicamente, de mudanças significativas para cada versão de um projeto 19 | *open source*. 20 | 21 | 
#{File.read("CHANGELOG.md")}
22 | 23 | :markdown 24 | ### Para que serve um *changelog*? 25 | 26 | Para facilitar que usuários e contribuidores vejam precisamente quais 27 | mudanças significativas foram realizadas entre cada versão publicada. 28 | 29 | ### Por que eu deveria me importar? 30 | 31 | Porque softwares são feitos para pessoas. Se você não liga, por que está 32 | contribuindo com projetos *open source*? Certamente deve haver um fundo de 33 | carinho em algum lugar desse seu amável cerebrinho. 34 | 35 | Eu [conversei com Adam Stacoviak e Jerod Santo no podcast do The 36 | Changelog][thechangelog] (faz sentido, hein?) sobre por que mantenedores e 37 | contribuidores *open source* devem se importar e as motivações por trás desse 38 | projeto. Se você tem tempo (1:06), é um bom programa. 39 | 40 | ### O que faz um *changelog* ser bom? 41 | 42 | Que bom que perguntou. 43 | 44 | Um bom *changelog* se atém a esses princípios: 45 | 46 | - É feito para seres humanos, não máquinas, então legibilidade é crucial. 47 | - É fácil de referenciar (*linkar*) qualquer seção (por isso Markdown ao 48 | invés de puro texto). 49 | - Uma subseção por versão. 50 | - Lista as versões publicadas em ordem cronológica decrescente (mais novo em 51 | cima). 52 | - Usa todas as datas no formato `AAAA-MM-DD`. (Exemplo: `2012-06-02` para 53 | `2 de Junho de 2012`.) É internacional, [sensato](http://xkcd.com/1179/), e 54 | independente de língua. 55 | - Menciona explicitamente se o projeto segue o [Versionamento Semântico][semver]. 56 | - Cada versão deve: 57 | - Listar sua data de publicação no formato acima. 58 | - Agrupar mudanças descrevendo seus impactos no projeto, como segue: 59 | - `Added`/`Adicionado` para novas funcionalidades. 60 | - `Changed`/`Modificado` para mudanças em funcionalidades existentes. 61 | - `Deprecated`/`Obsoleto` para funcionalidades estáveis que foram removidas das 62 | próximas versões. 63 | - `Removed`/`Removido` para funcionalidades removidas desta versão. 64 | - `Fixed`/`Consertado` para qualquer correção de bug. 65 | - `Security`/`Segurança` para incentivar usuários a atualizarem em caso de 66 | vulnerabilidades. 67 | 68 | ### Como eu posso minimizar o esforço exigido? 69 | 70 | Mantenha sempre uma seção `"Unreleased"`\`"A publicar"` no topo para manter o controle de 71 | quaisquer mudanças. 72 | 73 | Isso serve a dois propósitos: 74 | 75 | - As pessoas podem ver quais mudanças elas podem esperar em publicações 76 | futuras. 77 | - No momento da publicação, você apenas tem de mudar o `"Unreleased"`\`"A publicar"` para o 78 | número de versão e adicionar um novo cabeçalho `"Unreleased"`\`"A publicar"` no topo. 79 | 80 | ### O que faz os unicórnios chorarem? 81 | 82 | Tudo bem... vamos lá. 83 | 84 | - **Despejar logs de commits.** Simplesmente não faça isso, você não está 85 | ajudando ninguém. 86 | - **Não dar ênfase nas obsolências.** Quando as pessoas atualizam de uma versão 87 | para outra, deve ser incrivelmente claro quando algo irá parar de funcionar. 88 | - **Datas em formatos específicos de uma região.** Nos Estados Unidos, as pessoas 89 | colocam o mês primeiro ("06-02-2012" para 2 de Junho de 2012, o que *não* 90 | faz sentido), enquanto muitos no resto do mundo escrevem em aspecto 91 | robótico "2 Junho 2012", e mesmo assim leem de forma diferente. 92 | "2012-06-02" funciona de maneira lógica do maior para o menor, não 93 | se confunde de maneira ambígua com outros formatos, e é um [padrão 94 | ISO](http://www.iso.org/iso/home/standards/iso8601.htm). Portanto, é o 95 | formato recomendado para *changelogs*. 96 | 97 | Tem mais. Ajude-me a coletar essas lágrimas de unicórnio [abrindo uma 98 | issue][issues] ou um *pull request*. 99 | 100 | ### Existe um padrão de formato de *changelog*? 101 | 102 | Infelizmente, não. Calma. Eu sei que você está buscando furiosamente 103 | aquele link do guia GNU de estilo de *changelog*, ou o arquivo "guideline" 104 | de dois paragráfos do GNU NEWS. O estilo GNU é um bom começo mas, infelizmente, é ingênuo. 105 | Não há nada de errado em ser ingênuo mas, quando as pessoas precisam de orientação, 106 | raramente ajuda. Especialmente quando existem muitas situações excepcionais 107 | para lidar. 108 | 109 | Este projeto [contém o que eu espero se tornar um melhor padrão de arquivo 110 | CHANGELOG][CHANGELOG] para todos os projetos *open source*. Eu não acredito que o status quo 111 | seja bom o suficiente, e acho que, como uma comunidade, nós podemos encontrar novas convenções 112 | se tentarmos extrair boas práticas de projetos de software reais. Por favor, dê uma olhada e 113 | lembre-se de que [discussões e sugestões de melhorias são bem-vindas][issues]! 114 | 115 | ### Qual deve ser o nome do arquivo *changelog*? 116 | 117 | Bom, se você não notou no exemplo acima, `CHANGELOG.md` é a melhor convenção até agora. 118 | 119 | Alguns outros projetos também utilizam `HISTORY.txt`, `HISTORY.md`, 120 | `History.md`, `NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, 121 | `RELEASE.md`, `releases.md`, etc. 122 | 123 | É uma bagunça. Todos esses nomes só dificultam encontrar o *changelog*. 124 | 125 | ### Por que as pessoas não podem simplesmente utilizar `git log`? 126 | 127 | Porque os logs do Git são cheios de ruído — por natureza. Eles não serviriam como um 128 | changelog adequado mesmo em um projeto hipotético executado por humanos perfeitos, que 129 | nunca erram uma letra, nunca esquecem de *commitar* arquivos, nunca cometem deslizes 130 | em uma refatoração. O propósito de um *commit* é documentar um passo atômico no 131 | processo pelo qual o código evolui de um estado a outro. O propósito de um *changelog* 132 | é documentar as diferenças relevantes entre esses estados. 133 | 134 | A mesma diferença que existe entre bons comentários e o código em si existe entre o 135 | *changelog* e o *commit log*: um descreve o *porquê*, o outro descreve o *como*. 136 | 137 | ### Podem os *changelogs* ser automaticamente interpretados? 138 | 139 | É difícil, porque as pessoas seguem formatos e nomes de arquivos 140 | radicalmente diferentes. 141 | 142 | [Vandamme][vandamme] é uma gem criada pelo time [Gemnasium][gemnasium] que 143 | interpreta muitos (mas não todos) *changelogs* de projetos *open source*. 144 | 145 | ### Por que você alterna entre as grafias "CHANGELOG" e "changelog"? 146 | 147 | "CHANGELOG" é o nome do arquivo em si. É um pouco chamativo mas é uma 148 | convenção histórica seguida por muitos projetos *open source*. Outros exemplos 149 | similares de arquivo incluem [`README`][README], [`LICENSE`][LICENSE], e 150 | [`CONTRIBUTING`][CONTRIBUTING]. 151 | 152 | O nome em letras maiúsculas (o que em sistemas operacionais antigos faziam 153 | estes arquivos ficarem no topo da lista) é utilizado para chamar atenção. 154 | Por conterem importantes metadados do projeto, *changelogs* são úteis a 155 | qualquer um que pretenda utilizar ou contribuir com o projeto, da maneira 156 | equivalente às [badges de projetos *open source*][shields]. 157 | 158 | Quando eu me refiro a "*changelog*", eu estou falando sobre a função desse 159 | arquivo: listar mudanças. 160 | 161 | ### E sobre as publicações removidas? 162 | 163 | Publicações removidas são versões que tiveram que ser removidas devido a um 164 | sério bug ou problema de segurança. Com frequência essas versões sequer 165 | aparecem em *changelogs*. Deveriam. É assim que você deve exibi-las: 166 | 167 | `## 0.0.5 - 2014-12-13 [YANKED]` 168 | 169 | A tag `[YANKED]`/`[REMOVIDA]` é chamativa por uma razão. É importante que 170 | as pessoas a notem. Além disso, já que é cercada por colchetes, é mais 171 | fácil detectá-la programaticamente. 172 | 173 | ### Devemos alterar o *changelog* em alguma circunstância? 174 | 175 | Claro. Sempre existem bons motivos para melhorar um *changelog*. Eu regularmente 176 | abro *pull requests* para adicionar versões faltantes em projetos *open source* 177 | com *changelogs* abandonados. 178 | 179 | Também é possível que você perceba que se esqueceu de registrar mudanças 180 | importantes nas notas de uma versão. É obviamente importante que você atualize 181 | seu *changelog* nesse caso. 182 | 183 | ### Como eu posso contribuir? 184 | 185 | Este documento não é a verdade; é minha cuidadosa opinião, junto com as 186 | informações e exemplos que reuni. Embora eu tenha providenciado um 187 | [CHANGELOG][] no [repositório no GitHub][gh], eu não criei de propósito uma 188 | lista clara de regras a serem seguidas (como o [SemVer.org][semver] faz, por 189 | exemplo). 190 | 191 | Fiz isso porque eu gostaria que nossa comunidade chegasse a um consenso. Eu 192 | acredito que a discussão é tão importante quanto o resultado final. 193 | 194 | Então, por favor, [entre em campo][gh]. 195 | 196 | [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md 197 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md 198 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE 199 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md 200 | [gemnasium]: https://gemnasium.com/ 201 | [gh]: https://github.com/olivierlacan/keep-a-changelog 202 | [issues]: https://github.com/olivierlacan/keep-a-changelog/issues 203 | [semver]: http://semver.org/ 204 | [shields]: http://shields.io/ 205 | [thechangelog]: http://5by5.tv/changelog/127 206 | [vandamme]: https://github.com/tech-angels/vandamme/ 207 | -------------------------------------------------------------------------------- /source/de/0.3.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: Keep a Changelog 3 | title: Keep a Changelog 4 | language: de 5 | version: 0.3.0 6 | --- 7 | 8 | :markdown 9 | # Führe ein CHANGELOG 10 | 11 | ## Lass Deine Freunde nicht CHANGELOGs mit git logs füllen™ 12 | 13 | Version **#{current_page.metadata[:page][:version]}** 14 | 15 | ### Was ist ein Changelog? 16 | Ein Changelog ist eine Datei, welche eine handgepflegte, chronologisch sortierte 17 | Liste aller erheblichen Änderungen enthält, die zwischen Veröffentlichungen (oder Versionen) 18 | des Projekts umgesetzt wurden. 19 | 20 | 
#{File.read("CHANGELOG.md")}
21 | 22 | ### Was ist der Zweck eines Changelogs? 23 | Es Benutzern und Entwicklern einfacher zu machen, gerade die beachtenswerten Änderungen, welche 24 | zwischen Veröffentlichungen (oder Versionen) des Projekts gemacht wurden, zu sehen. 25 | 26 | ### Warum sollte mich das kümmern? 27 | Weil Software-Werkzeuge für Menschen gemacht sind. Wenn es Dich nicht kümmert, warum 28 | trägst Du dann zu Open Source bei? Wenn Du tief in Dich gehst, findest Du bestimmt 29 | einen kleinen Teil, dem das wichtig ist. 30 | 31 | Ich [habe mit Adam Stacoviak and Jerod Santo im The Changelog-Podcast][thechangelog] (passt, oder?) 32 | darüber gesprochen (Englisch), weshalb sich Entwickler darum kümmern sollten und über die 33 | Beweggründe hinter diesem Projekt. Falls Du die Zeit hast (1:06), es lohnt sich, reinzuhören. 34 | 35 | ### Was macht ein gutes Changelog aus? 36 | Schön, dass Du fragst. 37 | 38 | Ein gutes Changelog hält sich an die folgenden Prinzipien: 39 | 40 | - Es ist für Menschen, nicht Maschinen, gemacht, deshalb ist Lesbarkeit entscheidend. 41 | - Es ist einfach, jeden Bereich zu verlinken (also besser Markdown als einfacher Text). 42 | - Ein Unterkapitel pro Version. 43 | - Liste die Releases in umgekehrt chronologischer Reihenfolge auf (neuestes zuoberst). 44 | - Schreib alle Daten im Format `JJJJ-MM-TT`. (Beispiel: `2012-06-02` für den `2. Juni 2012`.) Es ist international, [vernünftig](http://xkcd.com/1179/), und sprachunabhängig. 45 | - Erwähne explizit, ob das Projekt nach [Semantic Versioning][semver] geführt wird. 46 | - Jede Version sollte: 47 | - Das Release-Datum im oben genannten Format auflisten. 48 | - Änderungen wie folgt gruppieren, um ihren Einfluss auf das Projekt zu beschreiben: 49 | - `Added` für neue Features. 50 | - `Changed` für Änderungen an bestehender Funktionalität. 51 | - `Deprecated` für einst stabile Features, welche in zukünftigen Versionen entfernt werden. 52 | - `Removed` für Deprecated-Features, welche in dieser Version entfernt wurden. 53 | - `Fixed` für Bug-Fixes. 54 | - `Security` um Benutzer im Fall von Sicherheitsrisiken zu einer Aktualisierung aufzufordern. 55 | 56 | ### Wie kann ich den Aufwand so klein wie möglich halten? 57 | Hab immer einen `"Unreleased"`-Abschnitt zuoberst, um Änderungen im Auge zu behalten. 58 | 59 | Dies verfolgt zwei Ziele: 60 | 61 | - Man kann sehen, welche Änderungen in den nächsten Releases zu erwarten sind 62 | - Wenn es Zeit für den Release ist, kannst Du einfach `"Unreleased"` auf die 63 | Versionsnummer ändern und einen neuen `"Unreleased"`-Titel oben einfügen. 64 | 65 | ### Was bringt Einhörner zum weinen? 66 | Also… Schauen wir uns das an. 67 | 68 | - **Einen Diff von Commit-Logs ausgeben.** Mach das nicht, das hilft niemandem. 69 | - **Nicht mehr unterstützte Funktionen nicht hervorzuheben.** Wenn man von einer auf 70 | eine andere Version aktualisiert, sollte schmerzhaft klar sein, wenn dadurch etwas 71 | nicht mehr funktioniert. 72 | - **Datum in regionalen Formaten.** In den USA schreibt man den Monat zuerst 73 | ("06-02-2012" für den 2. Juni 2012, was *keinen* Sinn macht), während im Rest 74 | der Welt häufig ein roboterhaft aussehendes "2 June 2012" geschrieben, jedoch 75 | völlig anders ausgesprochen wird. "2012-06-02" funktioniert logisch vom grössten 76 | zum kleinsten Wert, überlagert sich nicht auf mehrdeutige Art mit anderen Datumsformaten 77 | und ist ein [ISO-Standard](http://www.iso.org/iso/home/standards/iso8601.htm). Deshalb 78 | ist es das empfohlene Datumsformat für Changelogs 79 | 80 | Das war noch nicht alles. Hilf mir, diese Einhorn-Tränen zu sammeln und [eröffne ein Issue][issues] 81 | oder einen Pull-Request. 82 | 83 | ### Gibt es ein standardisiertes Changelog-Format? 84 | Leider nicht. Beruhige Dich. Ich weiss, dass Du wie wild nach dem Link für den 85 | GNU Changelog Styleguide oder den zwei Absätze langen GNU NEWS-Datei "Leitfaden" 86 | suchst. Der GNU Styleguide ist ein guter Anfang, aber er ist leider sehr naiv. 87 | Es ist sicher nichts falsch daran, naiv zu zu sein, aber beim Verfassen eines Leitfadens 88 | ist es nicht wirklich hilfreich. Vor allem nicht, wenn es viele Spezialfälle zu beachten gibt. 89 | 90 | Dieses Projekt [enthält das, wovon ich hoffe, dass es zu einer besseren CHANGELOG-Datei-Konvention][CHANGELOG] 91 | wird. Ich glaube nicht, dass der status quo gut genug ist, und ich denke, dass wir als Community 92 | eine bessere Konvention entwickeln können, wenn wir Bewährtes aus echten 93 | Software-Projekten entnehmen. Schau Dich um und denk daran, dass 94 | [Diskussionen und Verbesserungsvorschläge sehr willkommen sind][issues]! 95 | 96 | ### Wie soll ich meine Changelog-Datei nennen? 97 | Nun, falls Du es noch nicht am Beispiel oben gesehen hast, `CHANGELOG.md` 98 | ist bisher die beste Konvention. 99 | 100 | Einige Projekte nutzen auch `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, 101 | `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc. 102 | 103 | Es ist ein Chaos. Alle diese Namen machen es nur schwerer, die Datei zu finden. 104 | 105 | ### Wieso sollte man nicht einfach ein `git log` Diff verwenden? 106 | Weil log Diffs voller unnötiger Information sind - von Natur aus. Sie wären nicht 107 | einmal ein geeignetes Changelog in einem hypothetischen Projekt, welches von perfekten 108 | Menschen geführt wird, welche sich niemals vertippen, niemals vergessen, neue Dateien 109 | zu comitten und nie einen Teil eines Refactorings übersehen. 110 | Der Zweck eines Commits ist es, einen atomaren Schritt eines Prozesses zu dokumentieren, 111 | welcher den Code von einem Zustand in den nächsten bringt. Der Zweck eines Changelogs 112 | ist es, die nennenswerten Veränderungen zwischen diesen Zuständen zu dokumentieren. 113 | 114 | Der Unterschied zwischen dem Changelog und dem Commit-Log ist wie der Unterschied 115 | zwischen guten Kommentaren und dem Code selbst: 116 | Das eine beschreibt das *wieso*, das andere das *wie*. 117 | 118 | ### Kann man Changelogs automatisiert parsen? 119 | Es ist nicht einfach, weil äusserst unterschiedliche Formate und Dateinamen verwendet 120 | werden. 121 | 122 | [Vandamme][vandamme] ist ein Ruby gem vom [Gemnasium][gemnasium]-Team, welches 123 | viele (aber nicht alle) Changelogs von Open-Source-Projekten parsen kann. 124 | 125 | ### Wieso schreibst Du mal "CHANGELOG" und mal "Changelog"? 126 | "CHANGELOG" ist der Name der Datei selbst. Es ist ein bisschen laut, aber 127 | es ist eine historische Konvention, welche von vielen Open-Source-Projekten 128 | angewendet wird. Andere Beispiele von ähnlichen Dateien sind [`README`][README], 129 | [`LICENSE`][LICENSE] und [`CONTRIBUTING`][CONTRIBUTING]. 130 | 131 | Die Grossschreibung (welche in alten Betriebssystemen dafür gesorgt hat, 132 | dass die Dateien zuerst aufgelistet wurden) wird verwendet, um die Aufmerksamkeit 133 | auf diese Dateien zu lenken. Da sie wichtige Metadaten über das Projekt enthalten, 134 | können sie wichtig für jeden sein, der das Projekt gerne benutzen oder mitentwickeln 135 | möchte, ähnlich wie [Open-Source-Projekt-Badges][shields]. 136 | 137 | Wenn ich über ein "Changelog" spreche, dann meine ich die Funktion der Datei: 138 | das Festhalten von Änderungen. 139 | 140 | ### Wie sieht es mit zurückgezogenen Releases aus? 141 | Sogenannte "Yanked Releases" sind Versionen, welche wegen schwerwiegenden 142 | Bugs oder Sicherheitsproblemen zurückgezogen werden mussten. Häufig kommen 143 | diese im Changelog gar nicht vor. Das sollten sie aber. So solltest Du diese 144 | darstellen: 145 | 146 | `## 0.0.5 - 2014-12-13 [YANKED]` 147 | 148 | Das `[YANKED]`-Tag ist aus einem guten Grund laut. Es ist wichtig, dass es 149 | wahrgenommen wird. Dass es von Klammern umfasst ist, vereinfacht auch 150 | das automatisierte Parsen. 151 | 152 | ### Sollte ich ein Changelog je umschreiben? 153 | Klar. Es gibt immer gute Gründe, ein Changelog zu verbessern. Ich öffne 154 | regelmässig Pull Requests um Open-Source-Projekten mit schlecht gewarteten 155 | Changelogs fehlende Releases hinzuzufügen. 156 | 157 | Es ist auch möglich, dass Du eine wichtige Änderung vergessen hast, in einer 158 | Version zu erwähnen. Natürlich ist es in diesem Fall wichtig, das Changelog 159 | zu aktualisieren. 160 | 161 | ### Wie kann ich mithelfen? 162 | Dieses Dokument ist nicht die **Wahrheit**; Es ist meine wohl überlegte Meinung, 163 | zusammen mit von mir zusammengetragenen Informationen und Beispielen. 164 | Obwohl ich im [GitHub-Repository][gh] ein [CHANGELOG][] führe, habe ich 165 | keine echten *Releases* oder klare zu befolgenden Regeln geschrieben (wie dies 166 | zum Beispiel [SemVer.org][semver] tut). 167 | 168 | Das ist so, weil ich möchte, dass die Community sich einig wird. Ich glaube, 169 | dass die Diskussion genau so wichtig wie das Endresultat ist. 170 | 171 | Deshalb [**pack bitte mit an**][gh]. 172 | 173 | [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md 174 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md 175 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE 176 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md 177 | [gemnasium]: https://gemnasium.com/ 178 | [gh]: https://github.com/olivierlacan/keep-a-changelog 179 | [issues]: https://github.com/olivierlacan/keep-a-changelog/issues 180 | [semver]: http://semver.org/ 181 | [shields]: http://shields.io/ 182 | [thechangelog]: http://5by5.tv/changelog/127 183 | [vandamme]: https://github.com/tech-angels/vandamme/ 184 | -------------------------------------------------------------------------------- /source/fr/0.3.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: Tenez un Changelog 3 | title: Tenez un Changelog 4 | language: fr 5 | version: 0.3.0 6 | --- 7 | 8 | :markdown 9 | # Tenez un CHANGELOG 10 | 11 | ## Ne laissez pas vos amis utiliser les logs git comme CHANGELOGs™ 12 | 13 | Version **#{current_page.metadata[:page][:version]}** 14 | 15 | ### Qu’est-ce qu’un journal des modifications (change log) ? 16 | Un journal des modifications (ou change log) est un fichier qui contient 17 | une liste triée chronologiquement des changements notables pour chaque 18 | version d’un projet 19 | 20 | 
#{File.read("CHANGELOG.md")}
21 | 22 | ### Quel est l’intérêt d’un change log ? 23 | Il permet aux utilisateurs et aux contributeurs de voir plus simplement 24 | les changements notables qui ont été réalisés entre chaque publication 25 | (ou version) du projet. 26 | 27 | ### Pourquoi devrais-je m’en préoccuper ? 28 | Parce que les logiciels sont pour les gens. Si vous ne vous en souciez pas, 29 | pourquoi contribuez-vous à l’open source ? Il doit sûrement y avoir un 30 | "kernel" (ha!) d’intérêt pour ça quelque part dans votre cher petit 31 | cerveau. 32 | 33 | J’ai [discuté avec Adam Stacoviak et Jerod Santo dans le podcast 34 | "The Changelog"][thechangelog] (approprié, non ?) des raisons pour 35 | lesquelles les mainteneurs et les contributeurs devraient s’en préoccuper ; 36 | également des motivations derrière ce projet. 37 | Si vous avez le temps (1:06), l’écoute vaut le coup. 38 | 39 | ### Qu’est-ce qui fait un bon change log ? 40 | Heureux de vous entendre le demander. 41 | 42 | Un bon change log se conforme à ces principes: 43 | 44 | - Il est fait pour des humains, pas des machines, la lisibilité est donc 45 | cruciale. 46 | - Facilité de faire un lien vers n’importe quelle section (d’où le Markdown 47 | plutôt que le text brut). 48 | - Une sous-section par version. 49 | - Liste les publications dans l’ordre chronologique inverse (les plus récentes 50 | en haut). 51 | - Toutes les dates sont au format `AAAA-MM-JJ`. (Exemple: `2012-06-02` pour le 52 | `2 Juin 2012`.) C’est international, [raisonnable](http://xkcd.com/1179/) et 53 | indépendant de la langue. 54 | - Mentionne explicitement si le projet respecte le 55 | [Versionnage Sémantique][semver]. 56 | - Chaque version devrait: 57 | - Lister sa date de publication au format ci-dessus. 58 | - Regrouper les changements selon leur impact sur le projet, comme suit: 59 | - `Added` pour les nouvelles fonctionnalités. 60 | - `Changed` pour les changements au sein des fonctionnalités déjà 61 | existantes. 62 | - `Deprecated` pour les fonctionnalités qui seront supprimées dans la 63 | prochaine publication. 64 | - `Removed` pour les anciennes fonctionnalités `Deprecated` qui viennent 65 | d’être supprimées. 66 | - `Fixed` pour les corrections de bugs. 67 | - `Security` pour encourager les utilisateurs à mettre à niveau afin 68 | d’éviter des failles de sécurité. 69 | 70 | ### Comment puis-je minimiser le travail nécessaire ? 71 | Ayez toujours une section `"Unreleased"` en haut du fichier afin de lister 72 | tous les changements pas encore publiés. 73 | 74 | Cela rempli deux objectifs: 75 | 76 | - Les gens peuvent voir les changements auxquels ils peuvent s’attendrent dans 77 | les prochaines publications 78 | - Au moment de la publication, vous n’avez qu’à remplacer `"Unreleased"` par 79 | la nouvelle version et rajouter une nouvelle section `"Unreleased"` 80 | au-dessus. 81 | 82 | ### Quelles sont les choses qui rendent tristes les licornes ? 83 | Très bien… parlons-en. 84 | 85 | - **Recopier les dernier logs git.** Ne faites simplement pas cela, vous 86 | n’aidez personne. 87 | - **Ne pas mettre l’accent sur les fonctionnalités dépréciées.** Quand les 88 | gens mettent à niveau d’une version vers une autre, le fait que quelque 89 | chose ne soit pas compatible devrait être évident. 90 | - **Les dates dans des formats spécifiques à une région.** Aux États-Unis, les 91 | gens mettent le mois en premier ("06-02-2012" pour le 2 Juin 2012, ce qui 92 | n’a *pas* de sens), tandis que beaucoup de gens dans le reste du monde 93 | l’écrivent de la façon robotique suivante "2 Juin 2012", alors qu’ils le 94 | prononcent différement. "2012-06-02" fonctionne logiquement, du plus grand 95 | au plus petit, ne laisse pas place à la confusion avec un autre format et 96 | est un [standard ISO](http://www.iso.org/iso/home/standards/iso8601.htm). 97 | Voilà pourquoi il est le format de dates recommandé pour les change logs. 98 | 99 | Il y en a d’autres. Aidez-moi à collecter ces larmes de licornes en 100 | [ouvrant une issue][issues] ou une pull request. 101 | 102 | ### Y a-t-il un format de change log standard ? 103 | Malheureusement, non. Du calme. Je sais que vous êtes en train de vous 104 | précipiter afin de trouver le lien vers le guide pour change logs GNU, ou le 105 | fichier GNU NEWS "guideline" de deux paragraphes. Le guide GNU est un bon 106 | début mais il est malheureusement simpliste. Il n'y a rien de mal avec le fait 107 | d'être simpliste, mais quand les gens ont besoin d'être guidés, ce n'est que 108 | rarement utile. Spécialement quand il a beaucoup de situations et de cas 109 | particuliers à prendre en compte. 110 | 111 | Ce projet [contient ce que j'espère devenir une meilleur convention pour les fichiers CHANGELOG][CHANGELOG]. 112 | Je ne pense pas que le status quo soit suffisant et je pense qu'en tant que 113 | communauté, nous pouvons arriver à de meilleures conventions si nous essayons 114 | d'extraire les meilleures pratiques depuis les vrais projets logiciels. S'il 115 | vous plaît, jetez-y un coup d'oeil et rappelez vous que les 116 | [discussions et les suggestions d'améliorations sont les bienvenues][issues]! 117 | 118 | ### Comment doit-être nommé le fichier de change log ? 119 | Eh bien, si l'exemple ci-dessus ne vous suffit pas à le deviner, 120 | `CHANGELOG.md` est la meilleure convention à ce jour. 121 | 122 | Certains projets utilisent aussi `HISTORY.txt`, `HISTORY.md`, `History.md`, 123 | `NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, 124 | `releases.md`, etc. 125 | 126 | C'est un véritable bazar. Tous ces noms ne font que rendre plus difficile son 127 | repérage par les gens. 128 | 129 | ### Pourquoi les gens ne recopient pas simplement les derniers logs git ? 130 | Parce que les logs gits sont remplis de bruit - par définition. Ils ne peuvent 131 | pas faire office de change log convenable, même dans un hypothétique projet 132 | tenu par des humains parfaits qui ne font jamais la moindre faute de frappe, 133 | n'oublient jamais de committer les nouveaux fichiers, ne manquent jamais 134 | aucune partie d'un refactoring. Le but d'un commit est de documenter une étape 135 | atomique dans le processus par lequel le code évolue d'un état à un autre. Le 136 | but d'un change log est de documenter les différences notables entre ces 137 | états. 138 | 139 | La différence entre des bons commentaires et le code lui-même est la même que 140 | celle entre un change log et les journaux git: l'un décrit le *pourquoi*, 141 | l'autre le comment. 142 | 143 | ### Les change logs peuvent-ils être parsés automatiquement ? 144 | C'est difficile, parce que les gens suivent des formats et utilisent des noms 145 | de fichiers très différents. 146 | 147 | [Vandamme][vandamme] est une Ruby gem 148 | créée par l'équipe [Gemnasium][gemnasium] qui parse les change logs de 149 | beaucoup (mais pas tous) de projets open source. 150 | 151 | ### Pourquoi cette alternance entre les graphies "CHANGELOG" et "change log" ? 152 | "CHANGELOG" est le nom pour le fichier même. C'est un peu imposant, mais dû à 153 | une convention historique suivie par beaucoup de projets open source. Il 154 | existe d'autres fichiers similaires, par exemple : [`README`][README], 155 | [`LICENSE`][LICENSE], and [`CONTRIBUTING`][CONTRIBUTING]. 156 | 157 | L'écriture en majuscule (qui dans les vieux systèmes d'exploitation faisait 158 | apparaître ces fichiers en haut) de ces noms de fichiers est utilisée pour 159 | attirer l'attention sur eux. Puisqu'ils font partie des méta-données 160 | importantes du projet, ils pourraient être utiles à quiconque voulant y 161 | l'utiliser ou y contribuer, tout comme les 162 | [badges de projet open source][shields]. 163 | 164 | Quand j'utilise la graphie "change log", je fais référence à la fonction de ce 165 | fichier: journaliser les changements. 166 | 167 | ### Qu'en est-il des publications "yanked" ? 168 | Les publications yanked sont des version qui ont dû être retirées du fait d'un 169 | sérieux bug ou d'un problème de sécurité. Souvent ces version n'apparaissent 170 | même pas dans les change logs. Elles devraient. Voilà comment les afficher: 171 | 172 | `## 0.0.5 - 2014-12-13 [YANKED]` 173 | 174 | Le tag `[YANKED]` n'est pas mis en avant pour rien. C'est important pour les 175 | gens de le remarquer. Puisqu'il est entouré par des crochets, c'est aussi plus 176 | facile à parser pour un programme. 177 | 178 | ### Devriez-vous réécrire un change log ? 179 | Bien sûr. Il y a toujours de bonnes raisons d'améliorer un change log. 180 | J'ouvre souvent des pull requests pour ajouter des publications manquantes sur 181 | des projets open source avec des change logs non-maintenus. 182 | 183 | Il est aussi possible que vous découvriez que vous aviez oublié de mentionner 184 | un changement majeur dans les notes de version. Il est évidemment important 185 | que vous mettiez votre change log à jour dans ce cas. 186 | 187 | ### Comment puis-je contribuer ? 188 | Ce document n'est pas la **vérité**; c'est mon opinion soigneusement 189 | réfléchie, accompagnée d'informations et d'exemples que j'ai rassemblés. 190 | Bien que je fournisse un véritable [CHANGELOG][] sur [le dépôt GitHub][gh], 191 | je n'ai volontairement pas créé de véritable *publication* ou de liste précise 192 | de règles à suivre (comme le fait [SemVer.org][semver], par exemple). 193 | 194 | C'est parce que je veux que notre communauté atteigne un consensus. Je crois 195 | que la discussion est aussi importante que le résultat final. 196 | 197 | Donc s'il vous plaît, [**mettez-vous y**][gh]. 198 | 199 | [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md 200 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md 201 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE 202 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md 203 | [gemnasium]: https://gemnasium.com/ 204 | [gh]: https://github.com/olivierlacan/keep-a-changelog 205 | [issues]: https://github.com/olivierlacan/keep-a-changelog/issues 206 | [semver]: http://semver.org/ 207 | [shields]: http://shields.io/ 208 | [thechangelog]: http://5by5.tv/changelog/127 209 | [vandamme]: https://github.com/tech-angels/vandamme/ 210 | -------------------------------------------------------------------------------- /source/sk/1.0.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: Udržuj changelog 3 | title: Udržuj changelog 4 | language: sk 5 | version: 1.0.0 6 | --- 7 | 8 | - changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md" 9 | - gemnasium = "https://gemnasium.com/" 10 | - gh = "https://github.com/olivierlacan/keep-a-changelog" 11 | - issues = "https://github.com/olivierlacan/keep-a-changelog/issues" 12 | - semver = "http://semver.org/" 13 | - shields = "http://shields.io/" 14 | - thechangelog = "http://5by5.tv/changelog/127" 15 | - vandamme = "https://github.com/tech-angels/vandamme/" 16 | - iso = "http://www.iso.org/iso/home/standards/iso8601.htm" 17 | - ghr = "https://help.github.com/articles/creating-releases/" 18 | 19 | .header 20 | .title 21 | %h1 Udržuj changelog 22 | %h2 Nenechaj kamarátov sypať git logy do changelogov. 23 | 24 | = link_to changelog do 25 | Verzia 26 | %strong= current_page.metadata[:page][:version] 27 | 28 | %pre.changelog= File.read("CHANGELOG.md") 29 | 30 | .answers 31 | %h3#what 32 | %a.anchor{ href: "#what", aria_hidden: "true" } 33 | Čo je to changelog? 34 | 35 | %p 36 | Changelog je súbor obsahujúci organizovaný, chronologicky usporiadaný 37 | zoznam významných zmien pre každú verziu daného projektu. 38 | 39 | %h3#why 40 | %a.anchor{ href: "#why", aria_hidden: "true" } 41 | Prečo udržiavať changelog? 42 | 43 | %p 44 | Aby používatelia a prispievatelia presne vedeli, aké podstatné zmeny 45 | sa udiali medzi jednotlivými vydaniami (alebo verziami) projektu. 46 | 47 | %h3#who 48 | %a.anchor{ href: "#who", aria_hidden: "true" } 49 | Kto potrebuje changelog? 50 | 51 | %p 52 | Ľudia. Či už konzumenti, alebo vývojári, koncoví používatelia softvéru 53 | sú ľudské bytosti, ktorým záleží na tom, čo softvér obsahuje. Keď sa 54 | softvér zmení, ľudia chcú vedieť prečo a ako. 55 | 56 | .good-practices 57 | %h3#how 58 | %a.anchor{ href: "#how", aria_hidden: "true" } 59 | Ako vytvorím dobrý changelog? 60 | 61 | %h4#principles 62 | %a.anchor{ href: "#principles", aria_hidden: "true" } 63 | Hlavné princípy 64 | 65 | %ul 66 | %li 67 | Changelogy sú pre ľudí, nie stroje. 68 | %li 69 | Changelog by mal obsahovať záznam pre každú jednu verziu. 70 | %li 71 | Rovnaké typy zmien by mali byť zoskupené. 72 | %li 73 | Mala by existovať možnosť odkazovať na jednotlivé verzie a sekcie. 74 | %li 75 | Posledná verzia je uvedená na prvom mieste. 76 | %li 77 | Pre každú verziu je uvedený dátum jej vydania. 78 | %li 79 | Uveď tiež, že sa držíš #{link_to "sémantického verziovania", semver}. 80 | 81 | %a.anchor{ href: "#types", aria_hidden: "true" } 82 | %h4#types Typy zmien 83 | 84 | %ul 85 | %li 86 | %code Added 87 | pre nové funkcie. 88 | %li 89 | %code Changed 90 | pre zmeny existujúcej funkcie. 91 | %li 92 | %code Deprecated 93 | pre funkcie, ktoré budú čoskoro odstránené. 94 | %li 95 | %code Removed 96 | pre odstránené funkcie. 97 | %li 98 | %code Fixed 99 | pre opravy chýb. 100 | %li 101 | %code Security 102 | v prípade bezpečnostných zraniteľností. 103 | 104 | .effort 105 | 106 | %h3#effort 107 | %a.anchor{ href: "#effort", aria_hidden: "true" } 108 | Ako minimalizovať úsilie vynaložené na udržiavanie changelogu? 109 | 110 | %p 111 | Udržuj Unreleased sekciu na začiatku changelogu 112 | pre nadchádzajúce zmeny. 113 | 114 | %p Má to dva dôvody: 115 | 116 | %ul 117 | %li 118 | Ľudia môžu vidieť, aké zmeny môžu očakávať v ďalších vydaniach 119 | %li 120 | V čase vydávania novej verzie môžeš presunúť zmeny z 121 | Unreleased sekcie do sekcie novej verzie 122 | 123 | .bad-practices 124 | %h3#bad-practices 125 | %a.anchor{ href: "#bad-practices", aria_hidden: "true" } 126 | Môžu byť changelogy zlé? 127 | 128 | %p Áno. Tu je hneď niekoľko spôsobov, ako môžu byť neužitočné. 129 | 130 | %h4#log-diffs 131 | %a.anchor{ href: "#log-diffs", aria_hidden: "true" } 132 | Diffy z commit logu 133 | 134 | %p 135 | Použitie diffov z commit logu ako changelog nie je dobrý nápad: 136 | sú plné balastu. Veci ako merge commity, commity s nejasnými názvami, 137 | zmeny dokumentácie a pod. 138 | 139 | %p 140 | Účel commitu je dokumentovanie kroku v evolúcii zdrojového kódu. 141 | Niektoré projekty commity prečisťujú, iné nie. 142 | 143 | %p 144 | Účelom changelogu je dokumentovanie významných zmien, často naprieč 145 | viacerými commitmi, a jasne ich komunikovať koncovému používateľovi. 146 | 147 | %h4#ignoring-deprecations 148 | %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } 149 | Ignorovanie oznámenia zastaralých funkcií 150 | 151 | %p 152 | Keď používatelia prechádzajú na novšiu verziu, musí byť jasné, čo sa 153 | rozbije. Mala by pre nich existovať možnosť prejsť na verziu so zoznamom 154 | zastaralých funkcií, tieto funkcie odstrániť a následne prejsť na verziu, 155 | kde sú tieto zastaralé funkcie už odstránené. 156 | 157 | %p 158 | Ak už nič iné, tak aspoň uveď zastaralé, odstránené funkcie a všetky zmeny, 159 | ktoré môžu niečo rozbiť, do changelogu. 160 | 161 | 162 | %h4#confusing-dates 163 | %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } 164 | Mätúce dátumy 165 | 166 | %p 167 | Regionálne formáty dátumov sa líšia naprieč svetom a často je zložité 168 | nájsť formát dátumu, ktorý by bol prívetivý a intuitívny pre všetkých 169 | používateľov. Výhodou dátumu vo formáte 2017-07-17 je poradie 170 | od najväčšej jednotky po najmenšiu: rok, mesiac, deň. Tento formát sa tiež 171 | neprekrýva s inými formátmi, ktoré zamieňajú pozíciu dňa a mesiaca. Kvôli 172 | týmto dôvodom spolu s faktom, že ide o #{link_to "ISO štandard", iso}, 173 | je tento formát odporučený pre záznamy v changelogu. 174 | 175 | %aside 176 | Je toho však viac. Pomôž mi zozbierať tieto antivzory 177 | = link_to "otvorením issue", issues 178 | alebo pull requestom. 179 | 180 | .frequently-asked-questions 181 | %h3#frequently-asked-questions 182 | %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" } 183 | Často kladené otázky 184 | 185 | %h4#standard 186 | %a.anchor{ href: "#standard", aria_hidden: "true" } 187 | Existuje štandardný formát pre changelog? 188 | 189 | %p 190 | Nie. Existuje GNU príručka pre štýl changelogu alebo dvojodstavcová 191 | GNU "smernica" pre NEWS súbor. Obe sú však nevhodné či nedostatočné. 192 | 193 | %p 194 | Tento projekt sa snaží byť 195 | = link_to "lepšou konvenciou pre changelog.", changelog 196 | Vychádza z pozorovania a zozbierania osvedčených postupov komunity okolo projektov s otvoreným zdrojovým kódom. 197 | 198 | %p 199 | Zdravá kritika, diskusia a návrhy na zlepšenie 200 | = link_to "sú vítané.", issues 201 | 202 | 203 | %h4#filename 204 | %a.anchor{ href: "#filename", aria_hidden: "true" } 205 | Ako by mal byť súbor changelogu pomenovaný? 206 | 207 | %p 208 | Nazvi ho CHANGELOG.md. Niektoré projekty používajú tiež 209 | HISTORY, NEWS alebo RELEASES. 210 | 211 | %p 212 | Je jednoduché myslieť si, že názov changelogu nie je taký dôležitý. 213 | Prečo však sťažovať koncovému používateľovi hľadanie významných zmien? 214 | 215 | %h4#github-releases 216 | %a.anchor{ href: "#github-releases", aria_hidden: "true" } 217 | A čo GitHub Releases? 218 | 219 | %p 220 | Je to skvelá iniciatíva. Služba #{link_to "Releases", ghr} môže byť použitá 221 | pre premenu git tagov (napríklad tagu v1.0.0) na bohaté 222 | poznámky k vydaniam manuálnym pridávaním týchto poznámok alebo získaním 223 | správ z anotovaných git tagov a vytvorením poznámok k vydaniu z nich. 224 | 225 | %p 226 | GitHub Releases vytvorí neprenosný changelog, ktorý môže byť zobrazený 227 | používateľom v rámci GitHubu. Je možné ich upraviť na veľmi podobný štýl, 228 | aký navrhuje projekt Udržuj changelog, tento postup však býva trochu 229 | zložitejší. 230 | 231 | %p 232 | Súčasná verzia GitHub Releases tiež nie je ľahko objaviteľná koncovým 233 | používateľom, na rozdiel od klasického súboru s názvom napísaným veľkými 234 | písmenami (README, CONTRIBUTING atď.). Ďalším 235 | menším problémom je, že v súčasnosti nepodporuje odkazy na commit logy 236 | medzi jednotlivými vydaniami. 237 | 238 | %h4#automatic 239 | %a.anchor{ href: "#automatic", aria_hidden: "true" } 240 | Môžu byť changelogy automaticky parsované? 241 | 242 | %p 243 | Je to zložité, pretože ľudia používajú rôzne formáty a názvy súborov. 244 | 245 | %p 246 | #{link_to "Vandamme", vandamme} je Ruby gem vytvorený tímom 247 | #{link_to "Gemnasium", gemnasium}, ktorý parsuje mnohé (ale nie všetky) 248 | changelogy projektov s otvoreným zdrojovým kódom. 249 | 250 | 251 | %h4#yanked 252 | %a.anchor{ href: "#yanked", aria_hidden: "true" } 253 | A čo spätne stiahnuté vydania? 254 | 255 | %p 256 | Stiahnuté vydania sú verzie, ktoré museli byť neskôr spätne odobraté 257 | kvôli vážnej chybe alebo bezpečnostným rizikám. Tieto verzie sa často 258 | v changelogu ani neobjavia. Ale mali by sa. Zobrazovať by sa mali takto: 259 | 260 | %p ## 0.0.5 - 2014-12-13 [YANKED] 261 | 262 | %p 263 | Tag [YANKED] kričí naschvál. Je dôležité, aby si ho ľudia 264 | všimli. Keďže je uzavretý zátvorkami, je tiež jednoduchšie ho programovo 265 | parsovať. 266 | 267 | 268 | %h4#rewrite 269 | %a.anchor{ href: "#rewrite", aria_hidden: "true" } 270 | Mal by sa changelog niekedy prepisovať? 271 | 272 | %p 273 | Samozrejme. Vždy sa nájde dobrý dôvod na vylepšenie changelogu. Sám často 274 | otváram pull requesty pre pridanie chýbajúceho vydania projektov 275 | s otvoreným kódom a neudržiavaným changelogom. 276 | 277 | %p 278 | Tiež môže nastať situácia, že v poznámkach k vydaniu určitej verzie sa 279 | zabudla spomenúť podstatná zmena. V takom prípade je samozrejme dôležité 280 | tento changelog aktualizovať. 281 | 282 | 283 | %h4#contribute 284 | %a.anchor{ href: "#contribute", aria_hidden: "true" } 285 | Ako môžem prispieť? 286 | 287 | %p 288 | Tento dokument nie je úplná pravda; je mojím starostlivo 289 | zváženým názorom spolu s informáciami a príkladmi, ktoré som zozbieral. 290 | 291 | %p 292 | Je tomu tak preto, aby komunita dosiahla určitý konsenzus. Verím, že 293 | diskusia je rovnako dôležitá ako samotný výsledok. 294 | 295 | %p 296 | Takže, prosím, #{link_to "prilož ruku k dielu", gh}. 297 | 298 | .press 299 | %h3 Rozhovory 300 | %p 301 | Zúčastnil som sa podcastu #{link_to "The Changelog", thechangelog}, 302 | kde sme sa rozprávali o tom, prečo by sa správci projektov a prispievatelia 303 | mali zaujímať o changelogy a tiež o motivácii za týmto projektom. 304 | --------------------------------------------------------------------------------