├── .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 │ │ ├── variables.sass │ │ ├── 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 ├── ja │ ├── 1.0.0 │ │ └── index.html.haml │ └── 1.1.0 │ │ └── index.html.haml ├── ko │ └── 1.0.0 │ │ └── index.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 ├── CONTRIBUTING.md ├── .gitignore ├── Rakefile ├── .github └── dependabot.yml ├── Gemfile ├── .editorconfig ├── LICENSE ├── README.md ├── CODE_OF_CONDUCT.md ├── Gemfile.lock ├── CHANGELOG.md └── config.rb /.ruby-version: -------------------------------------------------------------------------------- 1 | 2.7.0 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 | /.idea 9 | -------------------------------------------------------------------------------- /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/mnslarcher/keep-a-changelog/main/source/assets/images/logo.png -------------------------------------------------------------------------------- /source/assets/images/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mnslarcher/keep-a-changelog/main/source/assets/images/favicon.ico -------------------------------------------------------------------------------- /source/assets/images/bg-hero@2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mnslarcher/keep-a-changelog/main/source/assets/images/bg-hero@2x.png -------------------------------------------------------------------------------- /source/assets/images/bg-img1@2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mnslarcher/keep-a-changelog/main/source/assets/images/bg-img1@2x.png -------------------------------------------------------------------------------- /source/assets/images/bg-img2@2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mnslarcher/keep-a-changelog/main/source/assets/images/bg-img2@2x.png -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: bundler 4 | directory: "/" 5 | schedule: 6 | interval: daily 7 | time: "04:00" 8 | open-pull-requests-limit: 10 9 | ignore: 10 | - dependency-name: middleman 11 | versions: 12 | - 4.3.7 13 | -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source "https://rubygems.org" 2 | 3 | gem "addressable" 4 | gem "middleman", "~> 4.4.2" 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/variables.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 | -------------------------------------------------------------------------------- /source/assets/stylesheets/anchors.sass: -------------------------------------------------------------------------------- 1 | @import "variables" 2 | 3 | .anchor 4 | display: none 5 | font-style: normal 6 | font-weight: normal 7 | position: absolute 8 | right: 100% 9 | top: 0 10 | 11 | .anchor::before 12 | line-height: 3.2 13 | content: "∞" 14 | color: $color-ocre 15 | padding-right: 0.1em 16 | 17 | .anchor:hover 18 | a 19 | text-decoration: none 20 | -------------------------------------------------------------------------------- /.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 | @import "variables" 2 | 3 | .toc 4 | position: fixed 5 | z-index: 9999 6 | top: 10% 7 | left: 0 8 | 9 | ul 10 | list-style-position: inside 11 | list-style-type: decimal-leading-zero 12 | padding: 0 0 0 1em 13 | li 14 | padding-left: 1em 15 | line-height: 2 16 | a 17 | padding: 0 1em 18 | line-height: 2 19 | display: none 20 | 21 | span 22 | display: none 23 | 24 | li:hover 25 | color: $color-sand 26 | background: $color-black 27 | li:hover a 28 | color: $color-sand 29 | font-weight: bold 30 | background-color: $color-black 31 | display: inline-block 32 | -------------------------------------------------------------------------------- /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 | @import "variables" 2 | 3 | $break-small: em(480px) 4 | $break-medium: em(800px) 5 | $break-large: em(1024px) 6 | 7 | body 8 | margin: 0 9 | 10 | article 11 | margin: 0 auto 12 | max-width: 65em 13 | 14 | .main 15 | background-color: $color-white 16 | 17 | div 18 | padding-left: 5% 19 | padding-right: 5% 20 | padding-bottom: 3em 21 | 22 | aside 23 | background-color: lighten(desaturate($color-bark, 5%), 10%) 24 | margin-bottom: -3em 25 | margin-left: -5% 26 | margin-right: -5% 27 | margin-top: 3em 28 | padding: 2em 5% 29 | text-align: center 30 | 31 | aside & 32 | background-position: top 33 | 34 | article p 35 | font-size: 1.3em 36 | 37 | article code 38 | border-radius: 0.315em 39 | border: 1px solid #ccc 40 | padding: 0 0.3em 0.040em 41 | font-size: 0.9em 42 | 43 | article ul 44 | font-size: 1.1em 45 | line-height: 1.5 46 | list-style-type: square 47 | padding-left: 1em 48 | 49 | @media (min-width: 1077px) 50 | body 51 | margin: 8px 52 | 53 | .main 54 | margin-bottom: 2em 55 | 56 | div 57 | padding-left: 20% 58 | padding-right: 20% 59 | 60 | aside 61 | margin-left: -35% 62 | margin-right: -35% 63 | padding: 2em 20% 64 | -------------------------------------------------------------------------------- /source/assets/stylesheets/application.css.sass: -------------------------------------------------------------------------------- 1 | @import "variables" 2 | @import "layout" 3 | @import "anchors" 4 | @import "sections" 5 | 6 | html 7 | font: 16px/1.4 $base-font-family 8 | color: #342828 9 | background-color: $color-sand 10 | 11 | a 12 | color: $color-ocre 13 | text-decoration: none 14 | 15 | a:hover 16 | text-decoration: underline 17 | 18 | h1 19 | color: $color-ocre 20 | font-size: 3.2em 21 | font-weight: bold 22 | font-family: $base-font-family 23 | margin-bottom: 0 24 | line-height: 1 25 | text-transform: lowercase 26 | 27 | h2 28 | font-size: 1.2em 29 | margin-top: 0.2em 30 | margin-bottom: 2em 31 | 32 | h1, h2 33 | text-align: left 34 | 35 | h3 36 | font-size: 1.3em 37 | font-family: $base-font-family 38 | margin-bottom: 1em 39 | position: relative 40 | padding-left: .1em 41 | 42 | h3:hover .anchor, h3:focus .anchor 43 | display: block 44 | 45 | h3 ~ p 46 | margin-top: 0 47 | 48 | h1, h2, h3 49 | margin-top: 0 50 | padding-top: 1em 51 | 52 | .about 53 | text-align: center 54 | 55 | .about 56 | margin-top: 0 57 | 58 | header 59 | .locales, .mark 60 | margin-bottom: -2em 61 | margin-top: 2em 62 | margin-right: 2em 63 | 64 | .mark 65 | margin-left: 3em 66 | float: left 67 | 68 | .footer 69 | line-height: 2.2 70 | 71 | .mark 72 | float: left 73 | 74 | .locales 75 | float: right 76 | 77 | .locales li 78 | float: right 79 | font-size: 0.7em 80 | display: inline 81 | list-style-type: none 82 | white-space: nowrap 83 | 84 | pre, code 85 | background-color: $color-light-sand 86 | font-family: $source-code-font-family 87 | code 88 | white-space: nowrap 89 | 90 | @media (min-width: 1077px) 91 | h1 92 | width: 50% 93 | -------------------------------------------------------------------------------- /source/assets/images/keep-a-changelog-mark.svg: -------------------------------------------------------------------------------- 1 | Artboard 1 copy 3 -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Keep a Changelog 2 | 3 | [![Keep a Changelog v1.1.0 badge][changelog-badge]][changelog] [![Version 1.1.0 Badge][version-badge]][changelog] [![MIT License Badge][license-badge]][license] 4 | 5 | Don’t let your friends dump git logs into changelogs™ 6 | 7 | This repository generates https://keepachangelog.com/. 8 | 9 | ## Development 10 | 11 | ### Dependencies 12 | 13 | - Ruby ([see version][ruby-version], [rbenv][rbenv] recommended) 14 | - Bundler (`gem install bundler`) 15 | 16 | ### Installation 17 | 18 | - `git clone https://github.com/olivierlacan/keep-a-changelog.git` 19 | - `cd keep-a-changelog` 20 | - `bundle install` 21 | - `bundle exec middleman` starts the local development server at http://localhost:4567 22 | 23 | ### Deployment 24 | 25 | - `bundle exec rake publish` builds and pushes to the `gh-pages` branch 26 | 27 | ### Translations 28 | 29 | Create a new directory in [`source/`][source] named after the ISO 639-1 code 30 | for the language you wish to translate Keep a Changelog to. For example, 31 | assuming you want to translate to French Canadian: 32 | 33 | - create the `source/fr-CA` directory. 34 | - duplicate the `source/en/1.0.0/index.html.haml` file in `source/fr-CA`. 35 | - edit `source/fr-CA/1.0.0/index.html.haml` until your translation is ready. 36 | - commit your changes to your own [fork][fork] 37 | - submit a [Pull Request][pull-request] with your changes 38 | 39 | It may take some time to review your submitted Pull Request. Try to involve a 40 | few native speakers of the language you're translating to in the Pull Request 41 | comments. They'll help review your translation for simple mistakes and give us 42 | a better idea of whether your translation is accurate. 43 | 44 | ## Contribute 45 | 46 | Please do contribute! Issues and pull requests are welcome. 47 | 48 | Thank you for your help improving software one changelog at a time! 49 | 50 | [changelog]: ./CHANGELOG.md 51 | [changelog-badge]: https://img.shields.io/badge/changelog-Keep%20a%20Changelog%20v1.1.0-%23E05735 52 | [license]: ./LICENSE 53 | [rbenv]: https://github.com/rbenv/rbenv 54 | [ruby-version]: .ruby-version 55 | [source]: source/ 56 | [pull-request]: https://help.github.com/articles/creating-a-pull-request/ 57 | [fork]: https://help.github.com/articles/fork-a-repo/ 58 | [version-badge]: https://img.shields.io/badge/version-1.1.0-blue.svg 59 | [license-badge]: https://img.shields.io/badge/license-MIT-blue.svg 60 | -------------------------------------------------------------------------------- /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 [https://contributor-covenant.org/version/1/4][version] 44 | 45 | [homepage]: https://contributor-covenant.org 46 | [version]: https://contributor-covenant.org/version/1/4/ 47 | -------------------------------------------------------------------------------- /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](https://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/main/CHANGELOG.md 138 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md 139 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE 140 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/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]: https://semver.org/lang/zh-CN/ 145 | [shields]: https://shields.io/ 146 | [thechangelog]: https://changelog.com/podcast/127 147 | [vandamme]: https://github.com/tech-angels/vandamme/ 148 | -------------------------------------------------------------------------------- /Gemfile.lock: -------------------------------------------------------------------------------- 1 | GEM 2 | remote: https://rubygems.org/ 3 | specs: 4 | activesupport (6.1.4.1) 5 | concurrent-ruby (~> 1.0, >= 1.0.2) 6 | i18n (>= 1.6, < 2) 7 | minitest (>= 5.1) 8 | tzinfo (~> 2.0) 9 | zeitwerk (~> 2.3) 10 | addressable (2.8.0) 11 | public_suffix (>= 2.0.2, < 5.0) 12 | autoprefixer-rails (10.2.5.0) 13 | execjs (< 2.8.0) 14 | backports (3.21.0) 15 | coderay (1.1.3) 16 | coffee-script (2.4.1) 17 | coffee-script-source 18 | execjs 19 | coffee-script-source (1.12.2) 20 | concurrent-ruby (1.1.9) 21 | contracts (0.13.0) 22 | dotenv (2.7.6) 23 | em-websocket (0.5.2) 24 | eventmachine (>= 0.12.9) 25 | http_parser.rb (~> 0.6.0) 26 | erubis (2.7.0) 27 | eventmachine (1.2.7) 28 | execjs (2.7.0) 29 | fast_blank (1.0.1) 30 | fastimage (2.2.5) 31 | ffi (1.15.4) 32 | haml (5.2.2) 33 | temple (>= 0.8.0) 34 | tilt 35 | hamster (3.0.0) 36 | concurrent-ruby (~> 1.0) 37 | hashie (3.6.0) 38 | htmlcompressor (0.2.0) 39 | http_parser.rb (0.6.0) 40 | i18n (1.6.0) 41 | concurrent-ruby (~> 1.0) 42 | kramdown (2.3.1) 43 | rexml 44 | listen (3.0.8) 45 | rb-fsevent (~> 0.9, >= 0.9.4) 46 | rb-inotify (~> 0.9, >= 0.9.7) 47 | memoist (0.16.2) 48 | method_source (1.0.0) 49 | middleman (4.4.2) 50 | coffee-script (~> 2.2) 51 | haml (>= 4.0.5) 52 | kramdown (>= 2.3.0) 53 | middleman-cli (= 4.4.2) 54 | middleman-core (= 4.4.2) 55 | middleman-autoprefixer (3.0.0) 56 | autoprefixer-rails (~> 10.0) 57 | middleman-core (>= 4.0.0) 58 | middleman-blog (4.0.3) 59 | addressable (~> 2.3) 60 | middleman-core (>= 4.0.0) 61 | tzinfo (>= 0.3.0) 62 | middleman-cli (4.4.2) 63 | thor (>= 0.17.0, < 2.0) 64 | middleman-core (4.4.2) 65 | activesupport (>= 6.1, < 7.0) 66 | addressable (~> 2.4) 67 | backports (~> 3.6) 68 | bundler (~> 2.0) 69 | contracts (~> 0.13.0) 70 | dotenv 71 | erubis 72 | execjs (~> 2.0) 73 | fast_blank 74 | fastimage (~> 2.0) 75 | hamster (~> 3.0) 76 | hashie (~> 3.4) 77 | i18n (~> 1.6.0) 78 | listen (~> 3.0.0) 79 | memoist (~> 0.14) 80 | padrino-helpers (~> 0.15.0) 81 | parallel 82 | rack (>= 1.4.5, < 3) 83 | sassc (~> 2.0) 84 | servolux 85 | tilt (~> 2.0.9) 86 | toml 87 | uglifier (~> 3.0) 88 | webrick 89 | middleman-gh-pages (0.4.1) 90 | rake (> 0.9.3) 91 | middleman-livereload (3.4.7) 92 | em-websocket (~> 0.5.1) 93 | middleman-core (>= 3.3) 94 | rack-livereload (~> 0.3.15) 95 | middleman-minify-html (3.4.1) 96 | htmlcompressor (~> 0.2.0) 97 | middleman-core (>= 3.2) 98 | middleman-syntax (3.2.0) 99 | middleman-core (>= 3.2) 100 | rouge (~> 3.2) 101 | minitest (5.14.4) 102 | padrino-helpers (0.15.1) 103 | i18n (>= 0.6.7, < 2) 104 | padrino-support (= 0.15.1) 105 | tilt (>= 1.4.1, < 3) 106 | padrino-support (0.15.1) 107 | parallel (1.21.0) 108 | parslet (2.0.0) 109 | pry (0.14.1) 110 | coderay (~> 1.1) 111 | method_source (~> 1.0) 112 | public_suffix (4.0.6) 113 | rack (2.2.3) 114 | rack-livereload (0.3.17) 115 | rack 116 | rake (13.0.1) 117 | rb-fsevent (0.11.0) 118 | rb-inotify (0.10.1) 119 | ffi (~> 1.0) 120 | redcarpet (3.5.1) 121 | rexml (3.2.5) 122 | rouge (3.7.0) 123 | sassc (2.4.0) 124 | ffi (~> 1.9) 125 | servolux (0.13.0) 126 | temple (0.8.2) 127 | thor (1.1.0) 128 | tilt (2.0.10) 129 | toml (0.3.0) 130 | parslet (>= 1.8.0, < 3.0.0) 131 | tzinfo (2.0.4) 132 | concurrent-ruby (~> 1.0) 133 | uglifier (3.2.0) 134 | execjs (>= 0.3.0, < 3) 135 | webrick (1.7.0) 136 | zeitwerk (2.5.1) 137 | 138 | PLATFORMS 139 | ruby 140 | 141 | DEPENDENCIES 142 | addressable 143 | middleman (~> 4.4.2) 144 | middleman-autoprefixer 145 | middleman-blog 146 | middleman-gh-pages 147 | middleman-livereload 148 | middleman-minify-html 149 | middleman-syntax 150 | pry 151 | redcarpet 152 | 153 | BUNDLED WITH 154 | 2.1.4 155 | -------------------------------------------------------------------------------- /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](https://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/main/CHANGELOG.md 138 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md 139 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE 140 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/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]: https://semver.org/lang/zh-CN/ 145 | [shields]: https://shields.io/ 146 | [thechangelog]: https://changelog.com/podcast/127 147 | [vandamme]: https://github.com/tech-angels/vandamme 148 | -------------------------------------------------------------------------------- /source/assets/stylesheets/sections.sass: -------------------------------------------------------------------------------- 1 | @import "variables" 2 | 3 | div.header 4 | padding-top: 5em 5 | padding-bottom: 0.1em 6 | background-color: $color-ocre 7 | background-image: image-url("bg-hero@2x.png") 8 | background-size: cover 9 | 10 | h1 11 | color: $color-sand 12 | 13 | h2 14 | font-weight: normal 15 | 16 | a 17 | color: $color-black 18 | 19 | .title 20 | width: 80% 21 | margin: 0 auto 22 | margin-bottom: -2em 23 | 24 | .changelog 25 | background-color: $color-white 26 | box-shadow: 0px 4px 12px 0px hsla(0, 0%, 0%, 0.2) 27 | font-size: 0.8em 28 | height: 20em 29 | margin-bottom: -14em 30 | margin-left: 0.5em 31 | margin-right: 0.5em 32 | margin-top: 1em 33 | overflow-x: auto 34 | padding: 1em 35 | 36 | div.answers 37 | margin-top: 12em 38 | padding-left: 5% 39 | padding-right: 5% 40 | background-color: $color-white 41 | 42 | h3 43 | font-size: 1.7em 44 | color: $color-ocre 45 | 46 | a 47 | color: $color-gold 48 | 49 | p 50 | font-size: 1em 51 | 52 | .good-practices 53 | background-color: $color-gold 54 | background-image: image-url("bg-img1@2x.png") 55 | background-position: bottom left 56 | background-repeat: no-repeat 57 | background-size: 100% 58 | padding-top: 2em 59 | 60 | a.anchor 61 | color: $color-black 62 | 63 | h3 64 | font-size: 1.6em 65 | font-weight: bold 66 | 67 | ul 68 | font-size: 1em 69 | 70 | p 71 | a 72 | color: $color-white 73 | text-decoration: underline 74 | 75 | div.bad-practices 76 | color: $color-white 77 | background-color: $color-bark 78 | background-image: image-url("bg-img2@2x.png") 79 | background-position: bottom left 80 | background-repeat: no-repeat 81 | background-size: 100% 82 | padding-top: 3em 83 | 84 | code 85 | color: $color-black 86 | background-color: desaturate(lighten($color-bark, 50%), 10%) 87 | border: none 88 | 89 | p, aside 90 | a 91 | color: $color-gold 92 | text-decoration: underline 93 | 94 | aside 95 | a 96 | text-decoration: none 97 | 98 | h3 99 | font-size: 1.7em 100 | color: $color-gold 101 | float: left 102 | 103 | 104 | p 105 | clear: left 106 | font-size: 1em 107 | 108 | div.effort 109 | padding-top: 2em 110 | padding-left: 5% 111 | padding-right: 5% 112 | background-color: $color-white 113 | 114 | h3 115 | font-size: 1.6em 116 | font-weight: bold 117 | color: $color-ocre 118 | 119 | div.frequently-asked-questions 120 | padding-top: 2em 121 | padding-left: 5% 122 | padding-right: 5% 123 | background-color: $color-white 124 | 125 | h2 126 | color: $color-ocre 127 | 128 | h3 129 | color: $color-ocre 130 | margin-bottom: 1.5em 131 | font-size: 1.7em 132 | 133 | h4 134 | cursor: pointer 135 | border-bottom: 1px solid transparentize($color-bark, 0.8) 136 | padding: 0 1.1em 1.3em 0 137 | 138 | &:after 139 | content: "⌄" 140 | text-align: right 141 | float: right 142 | font-size: 2.8em 143 | line-height: 0.4 144 | margin-right: -0.3em 145 | width: 1em 146 | text-align: center 147 | 148 | 149 | &.is-visible:after 150 | content: "-" 151 | 152 | h4 ~ p 153 | display: none 154 | font-size: 0.9em 155 | 156 | h4 ~ p.is-visible 157 | display: inherit 158 | 159 | .footer 160 | font-size: .6em 161 | font-weight: normal 162 | border-top: 1px solid #e9e6e1 163 | padding-top: 1em 164 | padding-left: 2em 165 | padding-right: 2em 166 | 167 | background-color: $color-ocre 168 | color: $color-sand 169 | 170 | a 171 | color: $color-white 172 | text-decoration: underline 173 | 174 | &:after 175 | content: "" 176 | display: table 177 | clear: both 178 | 179 | @media (min-width: 1077px) 180 | div.answers 181 | padding-left: 25% 182 | padding-right: 25% 183 | 184 | div.effort 185 | padding-left: 25% 186 | padding-right: 25% 187 | 188 | div.frequently-asked-questions 189 | padding-left: 25% 190 | padding-right: 25% 191 | 192 | .good-practices 193 | h3 194 | width: 50% 195 | h4 196 | padding-left: 15em 197 | ul 198 | padding-left: 16em 199 | 200 | .bad-practices 201 | h3 202 | width: 35% 203 | 204 | h4, p 205 | padding-left: 12em 206 | -------------------------------------------------------------------------------- /source/layouts/layout.html.haml: -------------------------------------------------------------------------------- 1 | // Variables 2 | - latest_version = current_page.metadata[:page][:version] == $last_version 3 | - legacy_version = current_page.metadata[:page][:version] < $last_version 4 | - language_code = current_page.metadata[:page][:language] 5 | - versions = Dir.entries("source/#{language_code}") - %w[. ..] 6 | - current_version = current_page.metadata[:page][:version] 7 | - newer_version_available = File.exists?("source/#{language_code}/#{$last_version}") 8 | 9 | !!! 5 10 | %html 11 | %head{ lang: current_page.data.language } 12 | %meta{ charset: 'utf-8' } 13 | %meta{ content: 'IE=edge', 'http-equiv' => 'X-UA-Compatible' } 14 | %meta{ name: 'viewport', content: 'width=device-width, initial-scale=1.0' } 15 | %meta{ name: 'description', content: current_page.data.description } 16 | 17 | -# Open Graph 18 | 19 | %meta{ property: 'og:article:publisher', content: config.publisher_url } 20 | %meta{ property: 'og:title', content: current_page.data.title } 21 | %meta{ property: 'og:type', content: 'article' } 22 | %meta{ property: 'og:url', content: path_to_url(current_page.url) } 23 | %meta{ property: 'og:description', content: current_page.data.description } 24 | %meta{ property: 'og:image', content: image_path("logo.png") } 25 | = yield_content :og 26 | 27 | -# Icons 28 | 29 | %link{ rel: "shortcut icon", type: "image/x-icon", href: image_path("favicon.ico") } 30 | %link{ rel: 'canonical', href: path_to_url(current_page.url) } 31 | 32 | %title= current_page.data.title 33 | 34 | %link{ rel: "stylesheet", href: "https://fonts.googleapis.com/css?family=Muli:400,700" } 35 | = stylesheet_link_tag '//fonts.googleapis.com/css?family=Source+Code+Pro:400,700' 36 | - if legacy_version 37 | = stylesheet_link_tag 'legacy' 38 | - else 39 | = stylesheet_link_tag 'application' 40 | = javascript_include_tag 'all', defer: true 41 | 42 | %body 43 | %article 44 | %header{ role: "banner" } 45 | - if latest_version 46 | = image_tag "keep-a-changelog-mark.svg", width: 100, class: "mark" 47 | %nav.locales{ role: "navigation" } 48 | %select 49 | - $languages.each do |language| 50 | - selected = language_code == language.first 51 | - if available_translation = available_translation_for(language) 52 | %option{ selected: selected, label: available_translation, value: language.first } 53 | = available_translation 54 | 55 | .main{ role: "main" } 56 | - if !latest_version && legacy_version 57 | - if versions.include?($last_version) 58 | %p.newer 59 | - if $languages[language_code][:new] 60 | = "#{$languages[language_code][:new]}: " 61 | - else 62 | There is a newer version available: 63 | = link_to "#{$languages[language_code][:name]} #{$last_version}", "/#{language_code}/#{$last_version}" 64 | - else 65 | - if $languages[language_code][:notice] 66 | %p.last-version-notice= $languages[language_code][:notice] 67 | - else 68 | %p.last-version-notice 69 | The latest version (#{$last_version}) is not yet available in 70 | this language but 71 | = link_to "you can read it in English", "/en/#{$last_version}" 72 | for now and 73 | = link_to "help translate ", "https://github.com/olivierlacan/keep-a-changelog/issues" 74 | it. 75 | 76 | = yield 77 | 78 | %footer.footer.clearfix{ role: "contentinfo" } 79 | = image_tag "keep-a-changelog-mark.svg", width: 30, height: 30, class: "mark" 80 | 81 | %p.about 82 | This project is 83 | = link_to "MIT Licensed", "https://choosealicense.com/licenses/mit/" 84 | \ // 85 | = link_to "Created & maintained", "https://github.com/olivierlacan/keep-a-changelog/" 86 | by 87 | = link_to "Olivier Lacan", "https://olivierlacan.com/" 88 | \ // 89 | Designed by 90 | = link_to "Tyler Fortune", "https://tylerfortune.me/" 91 | 92 | - unless config.gauges_id.blank? 93 | :javascript 94 | var _gauges = _gauges || []; 95 | (function() { 96 | var t = document.createElement('script'); 97 | t.type = 'text/javascript'; 98 | t.async = true; 99 | t.id = 'gauges-tracker'; 100 | t.setAttribute('data-site-id', '#{config.gauges_id}'); 101 | t.src = '//secure.gaug.es/track.js'; 102 | var s = document.getElementsByTagName('script')[0]; 103 | s.parentNode.insertBefore(t, s); 104 | })(); 105 | -------------------------------------------------------------------------------- /source/assets/images/logo.svg: -------------------------------------------------------------------------------- 1 | Artboard 1 -------------------------------------------------------------------------------- /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/main/CHANGELOG.md" 9 | - gh = "https://github.com/olivierlacan/keep-a-changelog" 10 | - issues = "https://github.com/olivierlacan/keep-a-changelog/issues" 11 | - semver = "https://semver.org/" 12 | - shields = "https://shields.io/" 13 | - thechangelog = "https://changelog.com/podcast/127" 14 | - vandamme = "https://github.com/tech-angels/vandamme/" 15 | - iso = "http://www.iso.org/iso/home/standards/iso8601.htm" 16 | - ghr = "https://help.github.com/articles/creating-releases/" 17 | 18 | .header 19 | .title 20 | %h1 如何维护更新日志 21 | %h2 更新日志绝对不应该是 git 日志的堆砌物 22 | 23 | = link_to changelog do 24 | Version 25 | %strong= current_page.metadata[:page][:version] 26 | 27 | %pre.changelog= File.read("CHANGELOG.md") 28 | 29 | .answers 30 | %h3#what 31 | %a.anchor{ href: "#what", aria_hidden: "true" } 32 | 更新日志是什么？ 33 | 34 | %p 35 | 更新日志（Change Log）是一个由人工编辑、以时间为倒序的列表，用于记录项目中每个版本的显著变动。 36 | 37 | %h3#why 38 | %a.anchor{ href: "#why", aria_hidden: "true" } 39 | 为何要提供更新日志？ 40 | 41 | %p 42 | 为了让用户和开发人员更简单清晰地知晓项目的不同版本之间有哪些显著变动。 43 | 44 | %h3#who 45 | %a.anchor{ href: "#who", aria_hidden: "true" } 46 | 哪些人需要更新日志？ 47 | 48 | %p 49 | 人人需要更新日志。无论是用户还是开发者。当软件有变动时，大家希望知道改动是为何、以及如何进行的。 50 | 51 | .good-practices 52 | %h3#how 53 | %a.anchor{ href: "#how", aria_hidden: "true" } 54 | 怎样制作高质量的更新日志？ 55 | 56 | %h4#principles 57 | %a.anchor{ href: "#principles", aria_hidden: "true" } 58 | 指导原则 59 | 60 | %ul 61 | %li 62 | 记住日志是写给人而非机器的。 63 | %li 64 | 每个版本都应该有独立的入口。 65 | %li 66 | 同类改动应该分组放置。 67 | %li 68 | 不同版本应分别设置链接。 69 | %li 70 | 新版本在前，旧版本在后。 71 | %li 72 | 应包括每个版本的发布日期。 73 | %li 74 | 注明是否遵守#{link_to "语义化版本规范", semver}。 75 | 76 | %a.anchor{ href: "#types", aria_hidden: "true" } 77 | %h4#types 变动类型 78 | 79 | %ul 80 | %li 81 | %code Added 82 | 新添加的功能。 83 | %li 84 | %code Changed 85 | 对现有功能的变更。 86 | %li 87 | %code Deprecated 88 | 已经不建议使用，即将移除的功能。 89 | %li 90 | %code Removed 91 | 已经移除的功能。 92 | %li 93 | %code Fixed 94 | 对 bug 的修复。 95 | %li 96 | %code Security 97 | 对安全性的改进。 98 | 99 | .effort 100 | 101 | %h3#effort 102 | %a.anchor{ href: "#effort", aria_hidden: "true" } 103 | 如何减少维护更新日志的精力？ 104 | 105 | %p 106 | 在文档最上方提供 Unreleased 区块以记录即将发布的更新内容。 107 | 108 | %p 这样做有两个好处： 109 | 110 | %ul 111 | %li 112 | 大家可以知道在未来版本中可能会有哪些变更。 113 | %li 114 | 在发布新版本时，直接将 Unreleased 区块中的内容移动至新发布版本的描述区块就可以了。 115 | 116 | .bad-practices 117 | %h3#bad-practices 118 | %a.anchor{ href: "#bad-practices", aria_hidden: "true" } 119 | 有很糟糕的更新日志吗？ 120 | 121 | %p 当然有，下面就是一些糟糕的方式。 122 | 123 | %h4#log-diffs 124 | %a.anchor{ href: "#log-diffs", aria_hidden: "true" } 125 | 使用 git 日志 126 | 127 | %p 128 | 使用 git 日志作为更新日志是个非常糟糕的方式：git 日志充满各种无意义的信息，如合并提交、语焉不详的提交标题、文档更新等。 129 | 130 | %p 131 | 提交的目的是记录源码的演化。一些项目会清理提交记录，一些则不会。 132 | 133 | %p 134 | 更新日志的目的则是记录重要的变更以供受众阅读，记录范围通常涵盖多次提交。 135 | 136 | %h4#ignoring-deprecations 137 | %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } 138 | 无视即将弃用的功能 139 | 140 | %p 141 | 当从一个版本升级至另一个时，人们应清楚（尽管痛苦）地知道哪些部分将不再被支持。应该允许先升级至一个列出哪些功能将会被弃用的版本，待去掉那些不再支持的部分后，再升级至把那些弃用功能真正移除的版本。 142 | 143 | %p 144 | 即使其他什么都不做，也至少要在更新日志中列出 derecations，removals 以及其他重大变动。 145 | 146 | %h4#confusing-dates 147 | %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } 148 | 易混淆的日期格式 149 | 150 | %p 151 | 不同区域有着不同的时间格式，要找到让大家都满意的日期格式不是件容易的事。2012-06-02 152 | 的格式从大到小排列符合逻辑、不容易与其他日期格式混淆，而且还符合 153 | #{link_to "ISO 标准", iso}。因此，推荐在更新日志中采用使用此种日期格式。 154 | 155 | %aside 156 | 还有更多内容？请通过 157 | = link_to "Issues", issues 158 | 或是 Pull Request 协助收集。 159 | 160 | .frequently-asked-questions 161 | %h3#frequently-asked-questions 162 | %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" } 163 | 常见问题 164 | 165 | %h4#standard 166 | %a.anchor{ href: "#standard", aria_hidden: "true" } 167 | 是否有一个标准化的更新日志格式？ 168 | 169 | %p 170 | 并没有。虽然 GNU 提供了更新日志样式指引，以及那个仅有两段长的 GNU NEWS 文件“指南”，但两者均远远不够。 171 | 172 | %p 173 | 此项目旨在提供一个 174 | #{link_to "更好的更新日志范例", changelog}，所有点子都来自于对开源社区中优秀实例的观察与记录。 175 | 176 | %p 177 | 欢迎#{link_to "提供", issues}有建设性的批评、讨论及建议。 178 | 179 | %h4#filename 180 | %a.anchor{ href: "#filename", aria_hidden: "true" } 181 | 更新日志文件应被如何命名？ 182 | 183 | %p 184 | 通常使用 CHANGELOG.md。有些项目将其命名为 185 | HISTORY、NEWS 或是 RELEASES。 186 | 187 | %p 188 | 当然，你可能认为更新日志的命名并不那么重要，但为什么要为难那些仅仅是想看到都有哪些重大变更的用户呢？ 189 | 190 | %h4#github-releases 191 | %a.anchor{ href: "#github-releases", aria_hidden: "true" } 192 | GitHub Releases 怎么样？ 193 | 194 | %p 195 | 这是个非常好的提议。#{link_to "GitHub Releases", ghr} 196 | 可通过手动添加发布日志或将带有注释的 git 标签信息抓取后转换的方式，将简单的 197 | git 标签（如一个叫 v1.0.0 的标签）转换为信息丰富的发布日志。 198 | 199 | %p 200 | GitHub Releases 会创建一个非便携、仅可在 GitHub 环境下显示的更新日志。尽管会花费更多时间，但将之处理成更新日志格式是完全可能的。 201 | 202 | %p 203 | 现行版本的 GitHub Releases 不像那些典型的大写文件（README，CONTRIBUTING 204 | 等），仍可以认为是不利于用户探索的。另一个小问题则是目前的 GitHub Releases 界面并没有提供不同版本间的 commit 日志链接。 205 | 206 | %h4#automatic 207 | %a.anchor{ href: "#automatic", aria_hidden: "true" } 208 | 更新日志可以被自动识别吗？ 209 | 210 | %p 211 | 非常困难，因为有各种不同的文件格式和命名。 212 | 213 | 214 | %p 215 | #{link_to "Vandamme", vandamme} 是一个 Ruby 程序，由 216 | Gemnasium 团队制作，可以解析多种（但绝对不是全部）开源库的更新日志。 217 | 218 | 219 | %h4#yanked 220 | %a.anchor{ href: "#yanked", aria_hidden: "true" } 221 | 那些后来撤下的版本怎么办？ 222 | 223 | %p 224 | 因重大 bug 或安全性原因而被撤下的版本通常不会出现在更新日志中，但仍然建议记录下来。你可以这样作出记录： 225 | 226 | %p ## [0.0.5] - 2014-12-13 [YANKED] 227 | 228 | %p 229 | 因为这类更改十分重要，所以 [YANKED] 标签应该非常醒目。此外，用方括号包围可使其更易被程序识别。 230 | 231 | 232 | %h4#rewrite 233 | %a.anchor{ href: "#rewrite", aria_hidden: "true" } 234 | 是否可以重写更新日志？ 235 | 236 | %p 237 | 当然可以。总会有合适的原因去改进更新日志。我也时常提 238 | Pull Request 来为那些未维护更新日志的开源项目加入缺失的发布信息。 239 | 240 | %p 241 | 另外，你很有可能发现自己忘记记录一个重大功能更新。这种情况下显然应该重写更新日志。 242 | 243 | 244 | %h4#contribute 245 | %a.anchor{ href: "#contribute", aria_hidden: "true" } 246 | 如何贡献？ 247 | 248 | %p 249 | 本文档并非真理。而是我深思熟虑后的建议，以及我收集的信息与样例。 250 | 251 | %p 252 | 希望我们的社区可以对此达成一致。我相信讨论的过程与最终结果一样重要。 253 | 254 | %p 255 | 所以欢迎#{link_to "贡献", gh}。 256 | 257 | .press 258 | %h3 访谈 259 | %p 260 | 我在 #{link_to "The Changelog podcast", thechangelog} 261 | 上讲述了为何维护者与贡献者应关心更新日志，以及这个项目背后的动机。 262 | -------------------------------------------------------------------------------- /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/main/CHANGELOG.md" 9 | - gh = "https://github.com/olivierlacan/keep-a-changelog" 10 | - issues = "https://github.com/olivierlacan/keep-a-changelog/issues" 11 | - semver = "https://semver.org/lang/zh-TW/" 12 | - shields = "https://shields.io/" 13 | - thechangelog = "https://changelog.com/podcast/127" 14 | - vandamme = "https://github.com/tech-angels/vandamme/" 15 | - iso = "http://www.iso.org/iso/home/standards/iso8601.htm" 16 | - ghr = "https://help.github.com/articles/creating-releases/" 17 | - gnu_changelog_styleguide = "https://www.gnu.org/prep/standards/html_node/Change-Logs.html" 18 | - gnu_the_news = "https://www.gnu.org/prep/standards/html_node/NEWS-File.html" 19 | 20 | .header 21 | .title 22 | %h1 如何維護更新日誌 23 | %h2 更新日誌絕對不應該只是 git log 的堆砌物 24 | 25 | = link_to changelog do 26 | Version 27 | %strong= current_page.metadata[:page][:version] 28 | 29 | %pre.changelog= File.read("CHANGELOG.md") 30 | 31 | .answers 32 | %h3#what 33 | %a.anchor{ href: "#what", aria_hidden: "true" } 34 | 更新日誌是什麼？ 35 | 36 | %p 37 | 更新日誌（Changelog）是個記錄專案演進版本間的差異，以時間倒敘、由人工攥寫的列表。 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 | .good-practices 54 | %h3#how 55 | %a.anchor{ href: "#how", aria_hidden: "true" } 56 | 如何寫出高品質的日誌？ 57 | 58 | %h4#principles 59 | %a.anchor{ href: "#principles", aria_hidden: "true" } 60 | 指導原則 61 | 62 | %ul 63 | %li 64 | 日誌是寫給「人」看的，不是機器。 65 | %li 66 | 每個版本都應該有獨立的進入點。 67 | %li 68 | 相同類型的改動應分組放置。 69 | %li 70 | 版本與章節應「可連結化」。 71 | %li 72 | 新版本總是寫在前面。 73 | %li 74 | 每個版本都該註記發佈日期。 75 | %li 76 | 版本命名應遵守#{link_to "語意化版本", semver}格式。 77 | 78 | %a.anchor{ href: "#types", aria_hidden: "true" } 79 | %h4#types 改動類型 80 | 81 | %ul 82 | %li 83 | %code Added 84 | 當增加了新功能。 85 | %li 86 | %code Changed 87 | 當更動了既有的功能。 88 | %li 89 | %code Deprecated 90 | 當功能將在近期被移除。 91 | %li 92 | %code Removed 93 | 當移除了現有的功能。 94 | %li 95 | %code Fixed 96 | 當修復了某些錯誤。 97 | %li 98 | %code Security 99 | 當增進了安全性漏洞。 100 | 101 | .effort 102 | 103 | %h3#effort 104 | %a.anchor{ href: "#effort", aria_hidden: "true" } 105 | 如何提升維護更新日誌的效率？ 106 | 107 | %p 108 | 在日誌上方使用 Unreleased 區塊記錄即將發佈的更新內容。 109 | 110 | %p 這麼做能夠： 111 | 112 | %ul 113 | %li 114 | 讓大家知道在未來的版本中可能會有哪些改動。 115 | %li 116 | 發佈新版本時，直接將 Unreleased 移到新版本的區塊就完成了 ヾ(*´ω｀*)ノ 117 | 118 | .bad-practices 119 | %h3#bad-practices 120 | %a.anchor{ href: "#bad-practices", aria_hidden: "true" } 121 | 難道日誌能寫得很糟嗎？ 122 | 123 | %p 當然。下面有些糟糕的範例： 124 | 125 | %h4#log-diffs 126 | %a.anchor{ href: "#log-diffs", aria_hidden: "true" } 127 | 🚫 直接使用 git log 128 | 129 | %p 130 | 使用 git log 作為更新日誌絕對不是個好主意：git log 充滿了各種無意義的訊息，像 merge commits 131 | 、亂七八糟的提交訊息、文件更新等。 132 | 133 | %p 134 | Commits 的目的應該是記錄原始碼的演化過程。有些項目會清理 commits，有些卻不會。 135 | 136 | %p 137 | 更新日誌的目的則是記錄那些值得一提的改動，經常涵蓋多個 commits，最終目的仍是讓使用者一目了然。 138 | 139 | %h4#ignoring-deprecations 140 | %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } 141 | 🚫 忽略 Deprecations 142 | 143 | %p 144 | 當使用者升級版本時，他應該要能預先知道哪些環節可能會出問題。理想的情形下，應該讓使用者有空間能預先升級即將被棄用的功能；待替換掉棄用功能之後，再升級至棄用功能被真正移除的版本。 145 | 146 | %p 147 | 即使不這麼做，也要在更新日誌中列出棄用的、移除的、或是任何可能導致程式碼失效的重大改動。 148 | 149 | %h4#confusing-dates 150 | %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } 151 | 🚫 易混淆的日期格式 152 | 153 | %p 154 | 在世界的每個角落，不同區域有著不同的時間格式，找到讓大家都滿意的日期格式不是件簡單的事。使用像 155 | 2017-07-17 的格式能清楚傳達日期、不易與其他日期格式混淆，同時也遵守 156 | #{link_to "ISO 標準", iso}，因此推薦使用像這樣的日期格式。 157 | 158 | %aside 159 | 其實還有許多應該避免的。大家可以透過 160 | = link_to "Issue", issues 161 | 或是 Pull Request 協助蒐集 ฅ' ω 'ฅ 162 | 163 | .frequently-asked-questions 164 | %h3#frequently-asked-questions 165 | %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" } 166 | 常見問題 167 | 168 | %h4#standard 169 | %a.anchor{ href: "#standard", aria_hidden: "true" } 170 | 有沒有標準格式可以參考呢？ 171 | 172 | %p 173 | 並沒有。雖然有 #{link_to "GNU 更新日誌指南", gnu_changelog_styleguide} 以及只有兩段長的 174 | #{link_to "GNU - The NEWS File 指南", gnu_the_news}（括弧笑），但這些並不足以稱為「標準」。 175 | 176 | %p 177 | 這項專案的宗旨在於提供一個 178 | #{link_to "更好的更新日誌範例", changelog}，源於觀察開源社群中優秀的實際案例，把它們蒐集在一起。 179 | 180 | %p 181 | 歡迎各位#{link_to "提供", issues}有建設性的建議和批評。 182 | 183 | %h4#filename 184 | %a.anchor{ href: "#filename", aria_hidden: "true" } 185 | 更新日誌的檔案名稱應該是？ 186 | 187 | %p 188 | 通常使用 CHANGELOG.md。也有用 189 | HISTORY、NEWS、或是 RELEASES 的例子。 190 | 191 | %p 192 | 或許你認為取什麼名字並不是件多麼重要的事，但為什麼要讓只是想看日誌的使用者不容易找到它呢？ 193 | 194 | %h4#github-releases 195 | %a.anchor{ href: "#github-releases", aria_hidden: "true" } 196 | 那麼 GitHub Releases 呢？ 197 | 198 | %p 199 | 這是個好問題。#{link_to "GitHub Releases", ghr} 200 | 能手動在簡單的 git tag（如 201 | v1.0.0） 上附加豐富的版本資訊，也能把附帶的 tag 202 | messages 轉換成漂亮的日誌格式。 203 | 204 | %p 205 | GitHub Releases 產生的日誌只能在 GitHub 上瀏覽，雖然 GitHub Releases 206 | 能做出接近本專案範例的日誌格式，但這會增加些許與 GitHub 的相依性。 207 | 208 | %p 209 | 現行的 GitHub Releases 210 | 畢竟不像典型的大寫文件（README、CONTRIBUTING 211 | 之類的），按理說會增加使用者找到的難度。另外還有個小問題，目前 GitHub 212 | Releases 頁面上並沒有提供兩版版本之間 commit logs 的連結。 213 | 214 | %h4#automatic 215 | %a.anchor{ href: "#automatic", aria_hidden: "true" } 216 | 更新日誌能被自動生成嗎？ 217 | 218 | %p 219 | 非常困難，各式各樣的提交訊息和檔案名稱難以完全掌握。 220 | 221 | %p 222 | 另外，有些開源專案使用由 Gemnasium 223 | 團隊開發的 #{link_to "Vandamme", vandamme} 224 | 轉換更新日誌，或許可以當作參考。 225 | 226 | %h4#yanked 227 | %a.anchor{ href: "#yanked", aria_hidden: "true" } 228 | 那麼被撤下的版本呢？ 229 | 230 | %p 231 | 因為重大漏洞或安全性問題而被撤下（unpublished）的版本通常不會出現在日誌裡，但建議仍然記錄下來。你可以這樣記錄它們： 232 | 233 | %p ## [0.0.5] - 2014-12-13 [YANKED] 234 | 235 | %p 236 | 其中 [YANKED] 標記應該和原因顯眼地標示在一起，讓使用者注意到它是最重要的事。此外，用中括弧能讓轉換用的程式更容易辨認它們。 237 | 238 | %h4#rewrite 239 | %a.anchor{ href: "#rewrite", aria_hidden: "true" } 240 | 可以更改過去版本的日誌內容嗎？ 241 | 242 | %p 243 | 當然可以，總是會有好的原因來改善以往寫下的日誌。我也時常發 pull request 244 | 給更新日誌不齊全的開源專案。 245 | 246 | %p 247 | 偶爾會發現自己遺漏了某項重大更新的紀錄，很明顯你應該補齊它們。 248 | 249 | %h4#contribute 250 | %a.anchor{ href: "#contribute", aria_hidden: "true" } 251 | 我能做些什麼嗎？ 252 | 253 | %p 254 | 這份文件並不是《真理》，而是我經過深思熟慮、遵循蒐集到的資訊和範例之後提出的建議。 255 | 256 | %p 257 | 源於我期望社群能達到共識，我相信討論的過程與結果一樣重要。 258 | 259 | %p 260 | 所以，#{link_to "加入我們", gh}吧 ٩(｡・ω・｡)و 261 | 262 | .press 263 | %h3 訪談 264 | %p 265 | 我在 #{link_to "The Changelog podcast", thechangelog} 上講述了為什麼維護者與協作者應該在意更新日誌，以及建立這項專案背後的契機。 266 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | All notable changes to this project will be documented in this file. 4 | 5 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 6 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). 7 | 8 | ## [Unreleased] 9 | 10 | ### Added 11 | 12 | - Added Dutch translation 13 | 14 | ### Fixed 15 | 16 | - Fixed foldouts in Dutch translation 17 | 18 | ## [1.1.0] - 2019-02-15 19 | 20 | ### Added 21 | 22 | - Danish translation from [@frederikspang](https://github.com/frederikspang). 23 | - Georgian translation from [@tatocaster](https://github.com/tatocaster). 24 | - Changelog inconsistency section in Bad Practices 25 | 26 | ### Changed 27 | 28 | - Fixed typos in Italian translation from [@lorenzo-arena](https://github.com/lorenzo-arena). 29 | - Fixed typos in Indonesian translation from [@ekojs](https://github.com/ekojs). 30 | 31 | ## [1.0.0] - 2017-06-20 32 | 33 | ### Added 34 | 35 | - New visual identity by [@tylerfortune8](https://github.com/tylerfortune8). 36 | - Version navigation. 37 | - Links to latest released version in previous versions. 38 | - "Why keep a changelog?" section. 39 | - "Who needs a changelog?" section. 40 | - "How do I make a changelog?" section. 41 | - "Frequently Asked Questions" section. 42 | - New "Guiding Principles" sub-section to "How do I make a changelog?". 43 | - Simplified and Traditional Chinese translations from [@tianshuo](https://github.com/tianshuo). 44 | - German translation from [@mpbzh](https://github.com/mpbzh) & [@Art4](https://github.com/Art4). 45 | - Italian translation from [@azkidenz](https://github.com/azkidenz). 46 | - Swedish translation from [@magol](https://github.com/magol). 47 | - Turkish translation from [@emreerkan](https://github.com/emreerkan). 48 | - French translation from [@zapashcanon](https://github.com/zapashcanon). 49 | - Brazilian Portuguese translation from [@Webysther](https://github.com/Webysther). 50 | - Polish translation from [@amielucha](https://github.com/amielucha) & [@m-aciek](https://github.com/m-aciek). 51 | - Russian translation from [@aishek](https://github.com/aishek). 52 | - Czech translation from [@h4vry](https://github.com/h4vry). 53 | - Slovak translation from [@jkostolansky](https://github.com/jkostolansky). 54 | - Korean translation from [@pierceh89](https://github.com/pierceh89). 55 | - Croatian translation from [@porx](https://github.com/porx). 56 | - Persian translation from [@Hameds](https://github.com/Hameds). 57 | - Ukrainian translation from [@osadchyi-s](https://github.com/osadchyi-s). 58 | 59 | ### Changed 60 | 61 | - Start using "changelog" over "change log" since it's the common usage. 62 | - Start versioning based on the current English version at 0.3.0 to help 63 | translation authors keep things up-to-date. 64 | - Rewrite "What makes unicorns cry?" section. 65 | - Rewrite "Ignoring Deprecations" sub-section to clarify the ideal 66 | scenario. 67 | - Improve "Commit log diffs" sub-section to further argument against 68 | them. 69 | - Merge "Why can’t people just use a git log diff?" with "Commit log 70 | diffs" 71 | - Fix typos in Simplified Chinese and Traditional Chinese translations. 72 | - Fix typos in Brazilian Portuguese translation. 73 | - Fix typos in Turkish translation. 74 | - Fix typos in Czech translation. 75 | - Fix typos in Swedish translation. 76 | - Improve phrasing in French translation. 77 | - Fix phrasing and spelling in German translation. 78 | 79 | ### Removed 80 | 81 | - Section about "changelog" vs "CHANGELOG". 82 | 83 | ## [0.3.0] - 2015-12-03 84 | 85 | ### Added 86 | 87 | - RU translation from [@aishek](https://github.com/aishek). 88 | - pt-BR translation from [@tallesl](https://github.com/tallesl). 89 | - es-ES translation from [@ZeliosAriex](https://github.com/ZeliosAriex). 90 | 91 | ## [0.2.0] - 2015-10-06 92 | 93 | ### Changed 94 | 95 | - Remove exclusionary mentions of "open source" since this project can 96 | benefit both "open" and "closed" source projects equally. 97 | 98 | ## [0.1.0] - 2015-10-06 99 | 100 | ### Added 101 | 102 | - Answer "Should you ever rewrite a change log?". 103 | 104 | ### Changed 105 | 106 | - Improve argument against commit logs. 107 | - Start following [SemVer](https://semver.org) properly. 108 | 109 | ## [0.0.8] - 2015-02-17 110 | 111 | ### Changed 112 | 113 | - Update year to match in every README example. 114 | - Reluctantly stop making fun of Brits only, since most of the world 115 | writes dates in a strange way. 116 | 117 | ### Fixed 118 | 119 | - Fix typos in recent README changes. 120 | - Update outdated unreleased diff link. 121 | 122 | ## [0.0.7] - 2015-02-16 123 | 124 | ### Added 125 | 126 | - Link, and make it obvious that date format is ISO 8601. 127 | 128 | ### Changed 129 | 130 | - Clarified the section on "Is there a standard change log format?". 131 | 132 | ### Fixed 133 | 134 | - Fix Markdown links to tag comparison URL with footnote-style links. 135 | 136 | ## [0.0.6] - 2014-12-12 137 | 138 | ### Added 139 | 140 | - README section on "yanked" releases. 141 | 142 | ## [0.0.5] - 2014-08-09 143 | 144 | ### Added 145 | 146 | - Markdown links to version tags on release headings. 147 | - Unreleased section to gather unreleased changes and encourage note 148 | keeping prior to releases. 149 | 150 | ## [0.0.4] - 2014-08-09 151 | 152 | ### Added 153 | 154 | - Better explanation of the difference between the file ("CHANGELOG") 155 | and its function "the change log". 156 | 157 | ### Changed 158 | 159 | - Refer to a "change log" instead of a "CHANGELOG" throughout the site 160 | to differentiate between the file and the purpose of the file — the 161 | logging of changes. 162 | 163 | ### Removed 164 | 165 | - Remove empty sections from CHANGELOG, they occupy too much space and 166 | create too much noise in the file. People will have to assume that the 167 | missing sections were intentionally left out because they contained no 168 | notable changes. 169 | 170 | ## [0.0.3] - 2014-08-09 171 | 172 | ### Added 173 | 174 | - "Why should I care?" section mentioning The Changelog podcast. 175 | 176 | ## [0.0.2] - 2014-07-10 177 | 178 | ### Added 179 | 180 | - Explanation of the recommended reverse chronological release ordering. 181 | 182 | ## [0.0.1] - 2014-05-31 183 | 184 | ### Added 185 | 186 | - This CHANGELOG file to hopefully serve as an evolving example of a 187 | standardized open source project CHANGELOG. 188 | - CNAME file to enable GitHub Pages custom domain 189 | - README now contains answers to common questions about CHANGELOGs 190 | - Good examples and basic guidelines, including proper date formatting. 191 | - Counter-examples: "What makes unicorns cry?" 192 | 193 | [unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.0...HEAD 194 | [1.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...v1.1.0 195 | [1.0.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0 196 | [0.3.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.2.0...v0.3.0 197 | [0.2.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.2.0 198 | [0.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.8...v0.1.0 199 | [0.0.8]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.7...v0.0.8 200 | [0.0.7]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.6...v0.0.7 201 | [0.0.6]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.5...v0.0.6 202 | [0.0.5]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.4...v0.0.5 203 | [0.0.4]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.3...v0.0.4 204 | [0.0.3]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.2...v0.0.3 205 | [0.0.2]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.1...v0.0.2 206 | [0.0.1]: https://github.com/olivierlacan/keep-a-changelog/releases/tag/v0.0.1 207 | -------------------------------------------------------------------------------- /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.glob("source/en/*").map{ |e| e.sub("source/en/","") }.sort 9 | # NOTE: for now, while 1.1.0 is in development let's pin the latest 10 | # version to 1.0.0 manually. 11 | # $last_version = $versions.last 12 | $last_version = "1.0.0" 13 | $previous_version = $versions[$versions.index($last_version) - 1] 14 | 15 | # This list of languages populates the language navigation. 16 | issues_url = 'https://github.com/olivierlacan/keep-a-changelog/issues' 17 | $languages = { 18 | "cs" => { 19 | name: "Čeština" 20 | }, 21 | "da" => { 22 | name: "Dansk", 23 | new: "En ny version er tilgængelig" 24 | }, 25 | "de" => { 26 | name: "Deutsch", 27 | notice: "Die neuste version (#{$last_version}) ist noch nicht auf Deutsch 28 | verfügbar, aber du kannst sie dir auf Englisch durchlesen 29 | und bei der Übersetzung mithelfen." 30 | }, 31 | "en" => { 32 | default: true, 33 | name: "English", 34 | new: "A new version is available" 35 | }, 36 | "es-ES" => { 37 | name: "Español", 38 | notice: "La última versión (#{$last_version}) aun no está disponible en 39 | Español, por ahora puedes leerla en Inglés y 40 | ayudar a traducirla." 41 | }, 42 | "fr" => { 43 | name: "Français", 44 | notice: "La dernière version (#{$last_version}) n'est pas encore disponible 45 | en français, mais vous pouvez la lire en anglais pour 46 | l'instant et aider à la traduire.", 47 | new: "Une nouvelle version est disponible" 48 | }, 49 | "hr" => { 50 | name: "Hrvatski" 51 | }, 52 | "id-ID" => { 53 | name: "Indonesia", 54 | new: "Ada versi baru tersedia" 55 | }, 56 | "it-IT" => { 57 | name: "Italiano", 58 | notice: "L'ultima versione (#{$last_version}) non è ancora disponibile in 59 | Italiano, ma la potete leggere in Inglese per ora e 60 | potete contribuire a tradurla." 61 | }, 62 | "ja" => { 63 | name: "日本語" 64 | }, 65 | "nl" => { 66 | name: "Nederlands" 67 | }, 68 | "pl" => { 69 | name: "polski" 70 | }, 71 | "pt-BR" => { 72 | name: "Português do Brasil", 73 | notice: "A última versão (#{$last_version}) ainda não está disponível em 74 | Português mas nesse momento você pode lê-la em inglês e 75 | ajudar em sua tradução." 76 | }, 77 | "ru" => { 78 | name: "Pyccкий", 79 | notice: "Самая последняя версия (#{$last_version}) ещё пока не переведена на 80 | русский, но вы можете прочитать её на английском и помочь с переводом." 82 | }, 83 | "sk" => { 84 | name: "Slovenčina" 85 | }, 86 | "ka" => { 87 | name: "ქართული" 88 | }, 89 | "sl" => { 90 | name: "Slovenščina" 91 | }, 92 | "sr" => { 93 | name: "Srpski" 94 | }, 95 | "sv" => { 96 | name: "Svenska", 97 | notice: "Den senaste versionen (#{$last_version}) är ännu inte tillgänglig på Svenska, 98 | men du kan läsa det på engelska och även hjälpa till att översätta det." 100 | }, 101 | "tr-TR" => { 102 | name: "Türkçe" 103 | }, 104 | "uk" => { 105 | name: "Українська" 106 | }, 107 | "zh-CN" => { 108 | name: "简体中文", 109 | notice: "最新版 (#{$last_version}) 暂时还没有翻译到简体中文，您可以阅读最新的英语版，并且帮助翻译，不胜感激。" 110 | }, 111 | "zh-TW" => { 112 | name: "正體中文", 113 | notice: "最新版 (#{$last_version}) 暫時還沒有翻譯到正體中文，您可以閱讀最新的英語版，並且幫助翻譯，不勝感激。" 114 | }, 115 | "ko" => { 116 | name: "한국어" 117 | }, 118 | "fa-IR" => { 119 | name: "فارسی" 120 | } 121 | } 122 | 123 | activate :i18n, 124 | lang_map: $languages, 125 | mount_at_root: :en 126 | 127 | set :gauges_id, '' 128 | set :publisher_url, 'https://www.facebook.com/olivier.lacan.5' 129 | set :site_url, 'https://keepachangelog.com' 130 | 131 | redirect "index.html", to: "en/#{$last_version}/index.html" 132 | 133 | $languages.each do |language| 134 | code = language.first 135 | versions = Dir.entries("source/#{code}").sort - %w[. ..] 136 | redirect "#{code}/index.html", to: "#{code}/#{versions.last}/index.html" 137 | end 138 | 139 | # ----- Assets ----- # 140 | 141 | set :css_dir, 'assets/stylesheets' 142 | set :js_dir, 'assets/javascripts' 143 | set :images_dir, 'assets/images' 144 | set :fonts_dir, 'assets/fonts' 145 | 146 | # ----- Images ----- # 147 | 148 | activate :automatic_image_sizes 149 | 150 | # ----- Markdown ----- # 151 | 152 | activate :syntax 153 | set :markdown_engine, :redcarpet 154 | 155 | ## Override default Redcarpet renderer in order to define a class 156 | class CustomMarkdownRenderer < Redcarpet::Render::HTML 157 | def doc_header 158 | %Q[] 159 | end 160 | 161 | def header(text, header_level) 162 | slug = text.parameterize 163 | tag_name = "h#{header_level}" 164 | anchor_link = "" 165 | header_tag_open = "<#{tag_name} id='#{slug}'>" 166 | 167 | output = "" 168 | output << header_tag_open 169 | output << anchor_link 170 | output << text 171 | output << "" 172 | 173 | output 174 | end 175 | end 176 | 177 | $markdown_config = { 178 | fenced_code_blocks: true, 179 | footnotes: true, 180 | smartypants: true, 181 | tables: true, 182 | with_toc_data: true, 183 | renderer: CustomMarkdownRenderer 184 | } 185 | set :markdown, $markdown_config 186 | 187 | # -------------------------------------- 188 | # Helpers 189 | # -------------------------------------- 190 | 191 | helpers do 192 | def path_to_url(path) 193 | Addressable::URI.join(config.site_url, path).normalize.to_s 194 | end 195 | 196 | def available_translation_for(language) 197 | language_name = language.last[:name] 198 | language_path = "source/#{language.first}" 199 | 200 | if File.exists?("#{language_path}/#{$last_version}") 201 | "#{$last_version} #{language_name}" 202 | elsif File.exists?("#{language_path}/#{$previous_version}") 203 | "#{$previous_version} #{language_name}" 204 | else 205 | nil 206 | end 207 | end 208 | end 209 | 210 | # -------------------------------------- 211 | # Content 212 | # -------------------------------------- 213 | 214 | # ----- Directories ----- # 215 | 216 | activate :directory_indexes 217 | page "/404.html", directory_index: false 218 | 219 | # -------------------------------------- 220 | # Production 221 | # -------------------------------------- 222 | 223 | # ----- Optimization ----- # 224 | 225 | configure :build do 226 | set :gauges_id, "5389808eeddd5b055a00440d" 227 | activate :asset_hash 228 | activate :gzip, {exts: %w[ 229 | .css 230 | .eot 231 | .htm 232 | .html 233 | .ico 234 | .js 235 | .json 236 | .svg 237 | .ttf 238 | .txt 239 | .woff 240 | ]} 241 | set :haml, { attr_wrapper: '"' } 242 | activate :minify_css 243 | activate :minify_html do |html| 244 | html.remove_quotes = false 245 | end 246 | activate :minify_javascript 247 | end 248 | 249 | # ----- Prefixing ----- # 250 | 251 | activate :autoprefixer do |config| 252 | config.browsers = ['last 2 versions', 'Explorer >= 10'] 253 | config.cascade = false 254 | end 255 | 256 | # Haml doesn't pick up on Markdown configuration so we have to remove the 257 | # default Markdown Haml filter and reconfigure one that follows our 258 | # global configuration. 259 | 260 | module Haml::Filters 261 | remove_filter("Markdown") #remove the existing Markdown filter 262 | 263 | module Markdown 264 | include Haml::Filters::Base 265 | 266 | def renderer 267 | $markdown_config[:renderer] 268 | end 269 | 270 | def render(text) 271 | Redcarpet::Markdown.new(renderer.new($markdown_config)).render(text) 272 | end 273 | end 274 | end 275 | -------------------------------------------------------------------------------- /source/ja/1.0.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: Keep a Changelog 3 | title: Keep a Changelog 4 | language: ja 5 | version: 1.0.0 6 | --- 7 | 8 | - changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/main/CHANGELOG.md" 9 | - gh = "https://github.com/olivierlacan/keep-a-changelog" 10 | - issues = "https://github.com/olivierlacan/keep-a-changelog/issues" 11 | - semver = "https://semver.org/" 12 | - shields = "https://shields.io/" 13 | - thechangelog = "https://changelog.com/podcast/127" 14 | - vandamme = "https://github.com/tech-angels/vandamme/" 15 | - iso = "http://www.iso.org/iso/home/standards/iso8601.htm" 16 | - ghr = "https://help.github.com/articles/creating-releases/" 17 | - gnustyle = "https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs" 18 | - gnunews = "https://www.gnu.org/prep/standards/html_node/NEWS-File.html#NEWS-File" 19 | 20 | .header 21 | .title 22 | %h1 変更履歴を記録する 23 | %h2 友達にGitログを変更履歴に移させないでください。 24 | 25 | = link_to changelog do 26 | Version 27 | %strong= current_page.metadata[:page][:version] 28 | 29 | %pre.changelog= File.read("CHANGELOG.md") 30 | 31 | .answers 32 | %h3#what 33 | %a.anchor{ href: "#what", aria_hidden: "true" } 34 | 変更履歴とは何ですか？ 35 | 36 | %p 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 | .good-practices 54 | %h3#how 55 | %a.anchor{ href: "#how", aria_hidden: "true" } 56 | 良い変更履歴を作るには？ 57 | 58 | %h4#principles 59 | %a.anchor{ href: "#principles", aria_hidden: "true" } 60 | 基本理念 61 | 62 | %ul 63 | %li 64 | 変更履歴は機械のためではなく人間のためにあります。 65 | %li 66 | バージョンごとに作成する必要があります。 67 | %li 68 | 同じ種類の変更をグループ化する必要があります。 69 | %li 70 | バージョンとセクションはリンク可能である必要があります。 71 | %li 72 | 最新バージョンは先頭にきます。 73 | %li 74 | 各バージョンのリリース日を表示されます。 75 | %li 76 | #{link_to "Semantic Versioning", semver} に従っているかどうか言及してください。 77 | 78 | %a.anchor{ href: "#types", aria_hidden: "true" } 79 | %h4#types 変更の種類 80 | 81 | %ul 82 | %li 83 | %code Added 84 | 新機能について。 85 | %li 86 | %code Changed 87 | 既存機能の変更について。 88 | %li 89 | %code Deprecated 90 | 間もなく削除される機能について。 91 | %li 92 | %code Removed 93 | 今回で削除された機能について。 94 | %li 95 | %code Fixed 96 | バグ修正について。 97 | %li 98 | %code Security 99 | 脆弱性に関する場合。 100 | 101 | .effort 102 | 103 | %h3#effort 104 | %a.anchor{ href: "#effort", aria_hidden: "true" } 105 | 変更履歴のメンテナンスに必要な労力を減らすにはどうすればよいですか？ 106 | 107 | %p 108 | 今後の変更を追跡するには Unreleased セクションを上部に配置します。 109 | 110 | %p これには2つの目的があります。 111 | 112 | %ul 113 | %li 114 | 人々は、今後のリリースでどのような変更が予想されるのかを確認することができます。 115 | %li 116 | リリース時には、 Unreleased セクションにある変更を 117 | 新しいリリースバージョンのセクションに移動することができます。 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 | コミットログの差分 129 | 130 | %p 131 | 変更履歴としてコミットログの差分を使用することはよくない考えです。それはノイズに満ちています。 132 | マージコミット、あいまいな表題のコミット、ドキュメントの変更などがあります。 133 | 134 | %p 135 | コミットの目的はソースコードの進化における一歩を文書化することです。 136 | コミットをクリーンアップするプロジェクトもあれば、そうでないプロジェクトもあります。 137 | 138 | %p 139 | 変更履歴エントリの目的は、しばしば複数のコミットにまたがって注目すべき違いを文書化し、 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 | あなたが他に何もしないのであれば、変更履歴に非推奨、削除、破壊的変更を列挙してください。 153 | 154 | 155 | %h4#confusing-dates 156 | %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } 157 | 分かりにくい日付 158 | 159 | %p 160 | 地域の日付形式は世界中で異なり、誰にとっても直感的でヒューマンフレンドリーな日付形式を見つけるのは困難です。 161 | 2017-07-17 のように形式化された日付の利点は、年、月、日のように最大から最小の単位の順序に従うということです。 162 | この形式は、月と日の位置を切り替える地域の形式とは異なり、他の日付形式とあいまいに重なり合うこともありません。 163 | これらの理由、およびこの日付形式が #{link_to "ISO standard", iso} であるという事実が、それが変更履歴エントリに推奨される日付形式である理由です。 164 | 165 | %aside 166 | これだけではありません。 167 | = link_to "Issueを開く", issues 168 | か、プルリクエストにてこれらのアンチパターンの収集を手伝ってください。 169 | 170 | .frequently-asked-questions 171 | %h3#frequently-asked-questions 172 | %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" } 173 | よくある質問と回答 174 | 175 | %h4#standard 176 | %a.anchor{ href: "#standard", aria_hidden: "true" } 177 | 変更履歴の標準的な書式がありますか？ 178 | 179 | %p 180 | 実はありません。 #{link_to "GNU changelog style guide", gnustyle} 、 181 | もしくは #{link_to "two-paragraph-long GNU NEWS file", gnunews} "guideline" があります。 182 | どちらも不十分であり不適切です。 183 | 184 | %p 185 | このプロジェクトは 186 | = link_to "より良い変更履歴の規約", changelog 187 | になることを目指しています。 188 | それはオープンソースコミュニティの良い習慣を観察し、それらを集めることから来ます。 189 | 190 | %p 191 | 健全な批判、議論、そして改善のための提案を 192 | = link_to "歓迎しています。", issues 193 | 194 | 195 | %h4#filename 196 | %a.anchor{ href: "#filename", aria_hidden: "true" } 197 | 変更履歴ファイルにはどのような名前をつけるべきですか？ 198 | 199 | %p 200 | CHANGELOG.md と呼びます。いくつかのプロジェクトでは 201 | HISTORY や NEWS 、 RELEASES が使われています。 202 | 203 | %p 204 | あなたの変更履歴ファイルの名前はそれほど重要でないと考えることは容易ですが、 205 | なぜエンドユーザーが一貫して注目の変更を見つけることを難しくするのですか？ 206 | 207 | %h4#github-releases 208 | %a.anchor{ href: "#github-releases", aria_hidden: "true" } 209 | GitHubリリースはどうですか？ 210 | 211 | %p 212 | 素晴らしい主導権です。 #{link_to "Releases", ghr} は手動でリリースノートを追加することによって、 213 | 単純なGitタグ(例えば v1.0.0 という名前のタグ)をリッチなリリースノートに変換するために使用することができます。 214 | 215 | %p 216 | Githubリリースは、Githubのコンテキスト内でのみユーザーに表示できる移植性のない変更履歴を作成します。 217 | それらをKeep a Changelogの書式のように見せることは可能ですが、もう少し複雑になる傾向があります。 218 | 219 | %p 220 | Githubリリースの現在のバージョンも、典型的な大文字のファイル(README や CONTRIBUTINGなど) 221 | とは異なり、おそらくエンドユーザーにはあまり発見できません。 222 | もう一つの目立たない問題は、インターフェースが現在各リリース間のコミット履歴へのリンクを提供していないということです。 223 | 224 | %h4#automatic 225 | %a.anchor{ href: "#automatic", aria_hidden: "true" } 226 | 変更履歴を自動的に解析できますか？ 227 | 228 | %p 229 | 人々は大きく異なるフォーマットやファイル名に従うので、難しいです。 230 | 231 | %p 232 | #{link_to "Vandamme", vandamme} はGemnasiumチームによって作成されたRuby gemであり、 233 | （全てではないが）多くのオープンソースプロジェクトの変更履歴を解析します。 234 | 235 | 236 | %h4#yanked 237 | %a.anchor{ href: "#yanked", aria_hidden: "true" } 238 | ヤンクリリースについてはどうですか？ 239 | 240 | %p 241 | ヤンクリリースは、深刻なバグやセキュリティの問題のために 242 | 引っ張られなければならなかったバージョンです。 243 | 多くの場合、これらのバージョンは変更履歴に表示されません。表示しないべきである。 244 | 次のように表示すべきである。 245 | 246 | %p ## [0.0.5] - 2014-12-13 [YANKED] 247 | 248 | %p 249 | [YANKED] は大きな理由です。それに気付くことは人々にとって重要です。 250 | 大括弧で囲まれているので、プログラムで解析するのも簡単です。 251 | 252 | 253 | %h4#rewrite 254 | %a.anchor{ href: "#rewrite", aria_hidden: "true" } 255 | 変更履歴を書き換える必要がありますか？ 256 | 257 | %p 258 | もちろんです。変更履歴を改善するためには、常にもっともな理由があります。 259 | メンテナンスされていない変更履歴のあるオープンソースプロジェクトに 260 | 不足しているリリースを追加するためのプルリクエストが常に開かれています。 261 | 262 | %p 263 | バージョンのノートにある破壊的変更への対応を忘れたことを発見するかもしれません。 264 | この場合、変更履歴を更新することは明らかに重要です。 265 | 266 | 267 | %h4#contribute 268 | %a.anchor{ href: "#contribute", aria_hidden: "true" } 269 | どうやって貢献できますか？ 270 | 271 | %p 272 | この文書は 真実 ではありません。 273 | 私が集めた情報と例と共に、慎重に考えられた私の意見です。 274 | 275 | %p 276 | 私たちのコミュニティが合意に達することを望んでいるからです。 277 | 私は議論が最終結果と同じくらい重要であると思います。 278 | 279 | %p 280 | なので #{link_to "協力", gh} してください。 281 | 282 | .press 283 | %h3 座談 284 | %p 285 | 私は #{link_to "The Changelog podcast", thechangelog} で、メンテナーやコントリビューターがなぜ変更履歴を気にすべきなのか、 286 | そしてこのプロジェクトの背後にある動機について話しました。 287 | -------------------------------------------------------------------------------- /source/ko/1.0.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: Keep a Changelog 3 | title: Keep a Changelog 4 | language: ko 5 | version: 1.0.0 6 | --- 7 | 8 | - changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/main/CHANGELOG.md" 9 | - gh = "https://github.com/olivierlacan/keep-a-changelog" 10 | - issues = "https://github.com/olivierlacan/keep-a-changelog/issues" 11 | - semver = "https://semver.org/" 12 | - shields = "https://shields.io/" 13 | - thechangelog = "https://changelog.com/podcast/127" 14 | - vandamme = "https://github.com/tech-angels/vandamme/" 15 | - iso = "http://www.iso.org/iso/home/standards/iso8601.htm" 16 | - ghr = "https://help.github.com/articles/creating-releases/" 17 | 18 | .header 19 | .title 20 | %h1 Changelog 관리 21 | %h2 동료가 git 로그를 changelogs에 덤프하게 내버려 두지 마세요. 22 | 23 | = link_to changelog do 24 | Version 25 | %strong= current_page.metadata[:page][:version] 26 | 27 | %pre.changelog= File.read("CHANGELOG.md") 28 | 29 | .answers 30 | %h3#what 31 | %a.anchor{ href: "#what", aria_hidden: "true" } 32 | Changelog는 무엇인가요? 33 | 34 | %p 35 | Changelog는 프로젝트의 각 버전에 대해 선별된 눈에 띄는 변경사항을 시간 순서대로 정리해둔 파일입니다. 36 | 37 | %h3#why 38 | %a.anchor{ href: "#why", aria_hidden: "true" } 39 | 왜 changelog를 유지해야 하나요? 40 | 41 | %p 42 | 사용자와 기여자가 프로젝트의 각 릴리즈(또는 버전)간에 정확히 어떤 주목할만한 변경사항이 있는지 보기 쉽도록 합니다. 43 | 44 | %h3#who 45 | %a.anchor{ href: "#who", aria_hidden: "true" } 46 | 누가 changelog를 필요로 하나요? 47 | 48 | %p 49 | 사람들이 필요로 합니다. 개발자이든 사용자이든, 소프트웨어의 최종 사용자는 소프트웨어에 무엇이 있는지 관심이 있는 사람입니다. 50 | 소프트웨어가 변할 때, 사람들은 왜 그리고 어떻게 바뀌었는지 알고 싶어합니다. 51 | 52 | .good-practices 53 | %h3#how 54 | %a.anchor{ href: "#how", aria_hidden: "true" } 55 | 어떻게 좋은 changelog를 만들수 있나요? 56 | 57 | %h4#principles 58 | %a.anchor{ href: "#principles", aria_hidden: "true" } 59 | 가이드 원칙 60 | 61 | %ul 62 | %li 63 | Changelogs는 사람을 위한 것입니다. 기계를 위한 것이 아닙니다. 64 | %li 65 | 모든 단일 버전에 대한 항목이 있어야 합니다. 66 | %li 67 | 같은 유형의 변경사항은 모아야 합니다. 68 | %li 69 | 버전과 섹션은 연결할 수 있어야 합니다. 70 | %li 71 | 최신 버전이 처음에 나옵니다. 72 | %li 73 | 각 버전의 릴리즈 날짜를 표시해야 합니다. 74 | %li 75 | #{link_to "시멘틱 버저닝", semver}를 따르는지 언급해 주세요. 76 | 77 | %a.anchor{ href: "#types", aria_hidden: "true" } 78 | %h4#types 변경 유형 79 | 80 | %ul 81 | %li 82 | %code Added 83 | 새로운 기능 84 | %li 85 | %code Changed 86 | 기존 기능의 변경사항 87 | %li 88 | %code Deprecated 89 | 곧 지워질 기능 90 | %li 91 | %code Removed 92 | 지금 지워진 기능 93 | %li 94 | %code Fixed 95 | 버그 픽스 96 | %li 97 | %code Security 98 | 취약점이 있는 경우 99 | 100 | .effort 101 | 102 | %h3#effort 103 | %a.anchor{ href: "#effort", aria_hidden: "true" } 104 | changelog를 관리하는 노력을 어떻게 줄일 수 있나요? 105 | 106 | %p 107 | Unreleased 섹션을 가장 위에 두어 다가올 변경사항을 추적할 수 있도록 하세요. 108 | 109 | %p 이것은 두 가지 용도로 사용됩니다: 110 | 111 | %ul 112 | %li 113 | 사람들이 다음 릴리즈에서 기대하는 변경사항을 확인할 수 있습니다. 114 | %li 115 | 릴리즈 시점에 Unreleased 섹션의 변경사항을 새 릴리즈 섹션으로 이동할 수 있습니다. 116 | 117 | .bad-practices 118 | %h3#bad-practices 119 | %a.anchor{ href: "#bad-practices", aria_hidden: "true" } 120 | changelogs가 안좋게 될 수 있습니까? 121 | 122 | %p 네. 여기에 changelog가 쓸모없게 되는 몇가지 경우들이 있습니다. 123 | 124 | %h4#log-diffs 125 | %a.anchor{ href: "#log-diffs", aria_hidden: "true" } 126 | 커밋 로그 차이(Commit log diffs) 127 | 128 | %p 129 | 커밋 로그 차이를 changelog로 사용하는 것은 안좋은 생각입니다: 130 | 머지 커밋, 모호한 타이틀을 가진 커밋, 문서 변경 등 노이즈로 가득차 있습니다. 131 | 132 | %p 133 | 커밋의 목적은 소스 코드 진화의 단계를 기록하기 위함입니다. 134 | 어떤 프로젝트는 커밋을 정리하지만, 어떤 프로젝트는 하지 않습니다. 135 | 136 | %p 137 | changelog 기입의 목적은 종종 다수의 커밋 중에서 주목할만한 차이를 138 | 최종 사용자에게 명확하게 전달하기 위해 문서화하는 것입니다. 139 | 140 | %h4#ignoring-deprecations 141 | %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } 142 | 없어질 기능들(Deprecations) 무시하기 143 | 144 | %p 145 | 사람들이 다른 버전으로 업그레이드 할 때, 언제 어떤 것이 손상될수있는지(breakable) 고통스럽게 분명해야 합니다. 146 | 앞으로 사라질 기능들(deprecations)이 나열된 버전으로 업그레이드하고, 147 | 더 이상 사용하지 않는 것(deprecated)을 제거한 뒤, 그 사라질 기능들이 148 | 정말 없어진 버전으로 업데이트 하는 것이 가능해야 합니다. 149 | 150 | %p 151 | 아무 작업도 수행하지 않는다면, 없어질 기능들, 제거된 것, 모든 급격한 변화를 changelog에 남기십시오. 152 | 153 | 154 | %h4#confusing-dates 155 | %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } 156 | 날짜를 혼동하는 것 157 | 158 | %p 159 | 지역 날짜 포맷은 전세계에 걸쳐 다르고 종종 모두에게 직관적인 인간 친화적 날짜 포맷을 찾기 힘듭니다. 160 | 2017-07-17 같은 날짜 포맷(연, 월, 일)의 장점은 161 | 큰 단위부터 작은 단위의 순서를 따른다는 것입니다. 162 | 월과 일의 위치가 뒤바뀐 어떤 포맷과 다르게, 이 포맷은 다른 날짜 포맷과 모호하게 겹치는 부분이 없습니다. 163 | 이런 이유와 이 포맷이 #{link_to "ISO standard", iso}라는 사실이 164 | changelog 기입을 위해 이 날짜 포맷을 추천하는 이유입니다. 165 | 166 | %aside 167 | 안티패턴은 더 있습니다. 168 | = link_to "이슈 오픈하기", issues 169 | 나 pull 요청을 통해 170 | 안티패턴들을 모으는 것을 도와주세요. 171 | 172 | .frequently-asked-questions 173 | %h3#frequently-asked-questions 174 | %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" } 175 | 자주 하는 질문 176 | 177 | %h4#standard 178 | %a.anchor{ href: "#standard", aria_hidden: "true" } 179 | changelog의 표준 포맷이 있나요? 180 | 181 | %p 182 | 없습니다. GNU changelog 스타일 가이드나 두 문단정도의 GNU NEWS '가이드라인'이 있습니다. 183 | 하지만 둘다 부적절하거나 충분하지 않습니다. 184 | 185 | %p 186 | 이 프로젝트의 목표는 187 | = link_to "더 나은 changelog 규칙", changelog 188 | 입니다. 189 | 이것은 오픈소스 커뮤니티에서 좋은 용례를 관찰하고 모으는데서 나옵니다. 190 | 191 | %p 192 | 건강한 비판, 토론 및 개선 제안은 193 | = link_to "환영합니다.", issues 194 | 195 | 196 | %h4#filename 197 | %a.anchor{ href: "#filename", aria_hidden: "true" } 198 | changelog 파일의 이름을 무엇으로 지어야 하나요? 199 | 200 | %p 201 | CHANGELOG.md라고 만드세요. 어떤 프로젝트는 202 | HISTORY, NEWS 또는 RELEASES를 사용합니다. 203 | 204 | %p 205 | changelog 파일의 이름이 무슨 상관이냐고 생각하기 쉽겠지만, 206 | 왜 굳이 여러분의 사용자가 변경사항을 일관적으로 찾기 힘들도록 만드나요? 207 | 208 | %h4#github-releases 209 | %a.anchor{ href: "#github-releases", aria_hidden: "true" } 210 | 깃허브 릴리즈는 어떻게 하나요? 211 | 212 | %p 213 | 이것은 훌륭한 이니셔티브입니다. #{link_to "릴리즈", ghr}는 214 | 직접 릴리즈 노트를 추가하거나 어노테이션된 깃 태그 메시지를 가져와서 노트로 바꿔 215 | 간단한 깃 태그(예를 들어 v1.0.0 태그 216 | )를 풍부한 릴리즈 노트로 전환시키는데 사용될 수 있습니다. 217 | 218 | %p 219 | 깃허브 릴리즈는 이동 불가능한 깃허브 컨텍스트 내에서만 표시되는 changelog를 생성합니다. 220 | Keep a Changelog 포맷처럼 보이게 만드는 게 가능하지만, 좀 더 복잡해지는 경향이 있습니다. 221 | 222 | %p 223 | 전형적인 대문자 파일들과 달리(README, CONTRIBUTING, 등), 224 | 깃허브 릴리즈의 현재 버전은 최종 사용자가 거의 찾아볼 수 없습니다. 225 | 다른 사소한 이슈는 인터페이스가 현재 각 릴리즈 사이에 로그를 커밋할 수 있는 링크를 제공하지 않는 것입니다. 226 | 227 | %h4#automatic 228 | %a.anchor{ href: "#automatic", aria_hidden: "true" } 229 | Changelog를 자동으로 파싱할 수 있나요? 230 | 231 | %p 232 | 사람들이 대단히 다양한 포맷과 파일 이름을 따르기 때문에 어렵습니다. 233 | 234 | %p 235 | #{link_to "Vandamme", vandamme}은 Gemnasium 팀에 의해 236 | 생성된 루비잼이고 많은(전부는 아니고) 오픈소스 프로젝트의 changelog를 파싱합니다. 237 | 238 | 239 | %h4#yanked 240 | %a.anchor{ href: "#yanked", aria_hidden: "true" } 241 | 삭제된 릴리즈(Yanked release)는 어떻게 하나요? 242 | 243 | %p 244 | 삭제된(Yanked) 릴리즈는 심각한 버그나 보안 이슈 때문에 소스에서 들어내버린 버전을 말합니다. 245 | 대게 이런 버전은 changelog에 아예 나오지도 않지만, 나와야 합니다. 이것이 삭제된 릴리즈를 246 | 표시하는 방법입니다: 247 | 248 | %p ## [0.0.5] - 2014-12-13 [YANKED] 249 | 250 | %p 251 | [YANKED] 태그가 요란한 이유가 있습니다. 252 | 사람들이 알아차리는 것이 중요합니다. 대괄호 안에 있기 때문에 프로그래밍적으로 파싱하기에도 용이합니다. 253 | 254 | 255 | %h4#rewrite 256 | %a.anchor{ href: "#rewrite", aria_hidden: "true" } 257 | changelog를 다시 써야하나요? 258 | 259 | %p 260 | 물론입니다. changelog를 개선할 좋은 이유는 항상 있습니다. 저는 정기적으로 261 | changelog가 관리되지 않는 오픈소스에 빠진 릴리즈를 추가하기 위해 pull request를 오픈합니다. 262 | 263 | %p 264 | 어떤 버전의 급격한 변화에 대해 언급하는 것을 잊은 것을 발견할 수도 있습니다. 265 | 이 경우엔 changelog를 업데이트하는 것이 당연히 중요합니다. 266 | 267 | 268 | %h4#contribute 269 | %a.anchor{ href: "#contribute", aria_hidden: "true" } 270 | 어떻게 기여할 수 있나요? 271 | 272 | %p 273 | 이 문서가 진리는 아닙니다. 이것은 제가 모은 정보와 예제들과 함께 274 | 신중하게 고려한 의견입니다. 275 | 276 | %p 277 | 왜냐하면 우리 커뮤니티가 공감대를 형성하기를 원하기 때문입니다. 저는 최종결과 못지않게 토론도 중요하다고 생각합니다. 278 | 279 | %p 280 | 그러니 #{link_to "참여", gh}를 부탁합니다. 281 | 282 | .press 283 | %h3 대화 284 | %p 285 | 왜 관리자와 기여자가 changelog를 신경써야하는지, 또한 이 프로젝트를 하게된 동기에 대해 이야기하기 위해 286 | #{link_to "The Changelog 팟캐스트", thechangelog}에 다녀왔습니다. 287 | -------------------------------------------------------------------------------- /source/ja/1.1.0/index.html.haml: -------------------------------------------------------------------------------- 1 | --- 2 | description: 変更履歴を記録する 3 | title: 変更履歴を記録する 4 | language: ja 5 | version: 1.1.0 6 | --- 7 | 8 | - changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/main//CHANGELOG.md" 9 | - gh = "https://github.com/olivierlacan/keep-a-changelog" 10 | - issues = "https://github.com/olivierlacan/keep-a-changelog/issues" 11 | - semver = "https://semver.org/" 12 | - shields = "https://shields.io/" 13 | - thechangelog = "https://changelog.com/podcast/127" 14 | - vandamme = "https://github.com/tech-angels/vandamme/" 15 | - iso = "http://www.iso.org/iso/home/standards/iso8601.htm" 16 | - ghr = "https://help.github.com/articles/creating-releases/" 17 | - gnustyle = "https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs" 18 | - gnunews = "https://www.gnu.org/prep/standards/html_node/NEWS-File.html#NEWS-File" 19 | 20 | .header 21 | .title 22 | %h1 変更履歴を記録する 23 | %h2 友達がGit記録を変更履歴に丸写しするのを止めさせよう。 24 | 25 | = link_to changelog do 26 | Version 27 | %strong= current_page.metadata[:page][:version] 28 | 29 | %pre.changelog= File.read("CHANGELOG.md") 30 | 31 | .answers 32 | %h3#what 33 | %a.anchor{ href: "#what", aria_hidden: "true" } 34 | 変更履歴とは何ですか？ 35 | 36 | %p 37 | 変更履歴とは、事業の各版に対する注目に値する変更点を 38 | 時系列順に並べた一覧を含むファイルです。 39 | 40 | %h3#why 41 | %a.anchor{ href: "#why", aria_hidden: "true" } 42 | なぜ変更履歴を記録するのですか？ 43 | 44 | %p 45 | 事業の各リリース（または各版）の間で、 46 | どのような注目すべき変更が行われたのかを利用者および貢献者が正確に把握しやすくするためです。 47 | 48 | %h3#who 49 | %a.anchor{ href: "#who", aria_hidden: "true" } 50 | 誰が変更履歴を必要としますか？ 51 | 52 | %p 53 | 全員が必要とします。 54 | 消費者であろうと開発者であろうと、ソフトウェアの末端利用者はソフトウェアの内容を気にします。 55 | ソフトウェアに変更があるとき、人々は変更の理由や方法を知りたいのです。 56 | 57 | .good-practices 58 | %h3#how 59 | %a.anchor{ href: "#how", aria_hidden: "true" } 60 | 良い変更履歴を作るには？ 61 | 62 | %h4#principles 63 | %a.anchor{ href: "#principles", aria_hidden: "true" } 64 | 基本理念 65 | 66 | %ul 67 | %li 68 | 変更履歴は機械のためではなく人間のためにあります。 69 | %li 70 | 版ごとに作成する必要があります。 71 | %li 72 | 同じ種類の変更をまとめる必要があります。 73 | %li 74 | 版と節はリンク可能である必要があります。 75 | %li 76 | 最新版は先頭にきます。 77 | %li 78 | 各版のリリース日を表示されます。 79 | %li 80 | #{link_to "Semantic Versioning", semver} に従っているかどうか言及してください。 81 | 82 | %a.anchor{ href: "#types", aria_hidden: "true" } 83 | %h4#types 変更の種類 84 | 85 | %ul 86 | %li 87 | %code Added 88 | 新機能について。 89 | %li 90 | %code Changed 91 | 既存機能の変更について。 92 | %li 93 | %code Deprecated 94 | 間もなく削除される機能について。 95 | %li 96 | %code Removed 97 | 今回で削除された機能について。 98 | %li 99 | %code Fixed 100 | 不具合修正について。 101 | %li 102 | %code Security 103 | 脆弱性に関する場合。 104 | 105 | .effort 106 | 107 | %h3#effort 108 | %a.anchor{ href: "#effort", aria_hidden: "true" } 109 | 変更履歴の維持管理に必要な労力を減らすにはどうすればよいですか？ 110 | 111 | %p 112 | 今後の変更を追跡するには Unreleased 節を上部に配置します。 113 | 114 | %p これには2つの目的があります。 115 | 116 | %ul 117 | %li 118 | 人々は、今後のリリースでどのような変更が予想されるのかを確認することができます。 119 | %li 120 | リリース時には、 Unreleased 節にある変更を 121 | 新しいリリース版の節に移動することができます。 122 | 123 | .bad-practices 124 | %h3#bad-practices 125 | %a.anchor{ href: "#bad-practices", aria_hidden: "true" } 126 | 変更履歴が害悪になる可能性はありますか？ 127 | 128 | %p はい、ありえます。 129 | 変更履歴を役立たずにしてしまう幾つかの行為をここに述べます。 130 | 131 | %h4#log-diffs 132 | %a.anchor{ href: "#log-diffs", aria_hidden: "true" } 133 | コミット記録の差分 134 | 135 | %p 136 | 変更履歴としてコミット記録の差分を使用することはよくない考えです。それは雑音に満ちています。 137 | コミット、あいまいな表題のコミット、文書の変更などがあります。 138 | 139 | %p 140 | コミットの目的はソースコードの進化における一歩を文書化することです。 141 | 合併コミットを一掃する事業もあれば、そうでない事業もあります。 142 | 143 | %p 144 | 変更履歴項目の目的は、しばしば複数のコミットにまたがって注目すべき違いを文書化し、 145 | それらを末端利用者に明確に伝えることです。 146 | 147 | %h4#ignoring-deprecations 148 | %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } 149 | 非推奨の無視 150 | 151 | %p 152 | 人々がある版から別の版に増強するとき、いつ何かが壊れるのは痛いほど明らかです。 153 | 廃止予定を洗い出した版に増強し、廃止予定のものを削除してから、 154 | 廃止予定が削除される版に増強することが可能です。 155 | 156 | %p 157 | あなたが他に何もしないのであれば、変更履歴に非推奨、削除、破壊的変更を列挙してください。 158 | 159 | %h4#confusing-dates 160 | %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } 161 | 分かりにくい日付 162 | 163 | %p 164 | 地域の日付形式は世界中で異なり、 165 | 誰にとっても直感的で親しみやすい日付形式を見つけるのは困難です。 166 | 2017-07-17 のように形式化された日付の利点は、 167 | 年、月、日のように最大から最小の単位の順序に従うということです。 168 | この形式は、月と日の位置を切り替える地域の形式とは異なり、 169 | 他の日付形式とあいまいに重なり合うこともありません。 170 | これらの理由、およびこの日付形式が #{link_to "国際標準", iso} であるという事実が、 171 | それが変更履歴項目に推奨される日付形式である理由です。 172 | 173 | %h4#inconsistent-changes 174 | %a.anchor{ href: "#inconsistent-changes", aria_hidden: "true" } 175 | 一貫性のない変更 176 | 177 | %p 178 | 変更履歴に全ての変更点を記載しないことは、変更履歴がないのと同じくらい危険です。 179 | たしかに記載しないでもよい変更は多くあります—— 180 | 例えば、空白を1つ削除したことはどんな場合でも記録する必要はないかもしれません—— 181 | が、重要な変更は全実例において記載すべきです。 182 | 変更を一貫して適用しないせいで、変更履歴こそ真実が記された唯一の情報源である 183 | という勘違いが生じる可能性があります。 184 | そして可能性は現実になりえます。 185 | 大いなる力には大いなる責任が伴います—— 186 | 良い変更履歴を作るというのは更新が一貫した変更履歴を作るということを意味します。 187 | 188 | %aside 189 | これだけではありません。 190 | = link_to "Issueを開く", issues 191 | か、プルリクエストして、こういった反面教師の収集を手伝ってください。 192 | 193 | .frequently-asked-questions 194 | %h3#frequently-asked-questions 195 | %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" } 196 | よくある質問と回答 197 | 198 | %h4#standard 199 | %a.anchor{ href: "#standard", aria_hidden: "true" } 200 | 変更履歴の標準的な書式がありますか？ 201 | 202 | %p 203 | 実はありません。 204 | #{link_to "GNU changelog style guide", gnustyle} 、もしくは 205 | #{link_to "two-paragraph-long GNU NEWS file", gnunews} という 206 | 「指針」があります。 207 | しかしどちらも不十分であり不適切です。 208 | 209 | %p 210 | この事業は 211 | = link_to "より良い変更履歴の規約", changelog 212 | になることを目指しています。 213 | それはオープンソース団体の良い習慣を観察し、それらを集めることから来ます。 214 | 215 | %p 216 | 健全な批判、議論、そして改善のための提案を 217 | = link_to "歓迎しています。", issues 218 | 219 | 220 | %h4#filename 221 | %a.anchor{ href: "#filename", aria_hidden: "true" } 222 | 変更履歴ファイルにはどのような名前をつけるべきですか？ 223 | 224 | %p 225 | CHANGELOG.md という名前にしましょう。 226 | いくつかの事業では HISTORY や NEWS 、 227 | RELEASES という名前が使われています。 228 | 229 | %p 230 | あなたの変更履歴ファイルの名前はそれほど重要でないと考えることは容易ですが、 231 | しかし末端利用者が注目に値する変更を一貫して見つけることを難しくする理由はありません。 232 | 233 | %h4#github-releases 234 | %a.anchor{ href: "#github-releases", aria_hidden: "true" } 235 | GitHubリリースはどうですか？ 236 | 237 | %p 238 | 極めて先駆的です。 #{link_to "Releases", ghr} に手動でリリース告知を追加することによって、 239 | 単純なGitタグ（例えば v1.0.0 という名前の標識）を素敵なリリース告知に変換するために使用できます。 240 | 241 | %p 242 | GitHub Releasesは、GitHubの文脈内でのみ利用者に表示できる移植性のない変更履歴を作成します。 243 | それらをKeep a Changelogの書式のように見せることは可能ですが、もう少し複雑になる傾向があります。 244 | 245 | %p 246 | GitHub Releasesの現在の版も、典型的な大文字のファイル 247 | （README や CONTRIBUTINGなど） 248 | とは異なり、おそらく末端利用者が見付けるのは簡単ではないでしょう。 249 | もう一つ目立たない問題として、現在、各リリース間のコミット履歴への 250 | リンクが提供されていないということがあります。 251 | 252 | %h4#automatic 253 | %a.anchor{ href: "#automatic", aria_hidden: "true" } 254 | 変更履歴を自動的に解析できますか？ 255 | 256 | %p 257 | 人々によって形式やファイル名は大きく異なるため、難しいです。 258 | 259 | %p 260 | #{link_to "Vandamme", vandamme} はGemnasiumチームが作成したRuby gemであり、 261 | （全てではありませんが）多くのオープンソース事業の変更履歴を解析できます。 262 | 263 | 264 | %h4#yanked 265 | %a.anchor{ href: "#yanked", aria_hidden: "true" } 266 | リリース引き戻しについてはどうですか？ 267 | 268 | %p 269 | リリース引き戻し (yanked releases) とは、深刻な不具合や安全上の問題のために 270 | リリースを引き戻さ (yank) なれなければならなかった版です。 271 | これらの変更はしばしば変更履歴に記載さえされませんが，必ず記載すべきです。 272 | 次のように表示すればよいでしょう。 273 | 274 | %p ## [0.0.5] - 2014-12-13 [YANKED] 275 | 276 | %p 277 | [YANKED] が仰々しいのには訳があります。 278 | 利用者が引き戻しに気付くことが重要だからです。 279 | 角括弧で囲まれているので、プログラムで解析するのも簡単です。 280 | 281 | 282 | %h4#rewrite 283 | %a.anchor{ href: "#rewrite", aria_hidden: "true" } 284 | 変更履歴を書き換える必要がありますか？ 285 | 286 | %p 287 | もちろんです。変更履歴を改善するためには、常にもっともな理由があります。 288 | 維持管理されていない変更履歴のあるオープンソース事業に、 289 | 不足している資源を追加するためのプルリクエストが常に開かれています。 290 | 291 | %p 292 | 版の告知にある破壊的変更への対応を忘れたことを発見するかもしれません。 293 | この場合、変更履歴を更新することは明らかに重要です。 294 | 295 | %h4#contribute 296 | %a.anchor{ href: "#contribute", aria_hidden: "true" } 297 | どうやって貢献できますか？ 298 | 299 | %p 300 | この文書は 真実 ではありません。 301 | 私が集めた情報と例と共に、慎重に考えられた私の意見です。 302 | 303 | %p 304 | 私たち一同が合意に達することを望んでいるからです。 305 | 私は議論が最終結果と同じくらい重要であると思います。 306 | 307 | %p 308 | なので #{link_to "協力", gh} してください。 309 | 310 | .press 311 | %h3 座談 312 | %p 313 | 私は #{link_to "The Changelog podcast", thechangelog} で、 314 | 管理者や貢献者がなぜ変更履歴を気にすべきなのか、 315 | そしてこの事業の背後にある動機について話しました。 316 | -------------------------------------------------------------------------------- /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](https://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/main/CHANGELOG.md 174 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md 175 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE 176 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/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]: https://semver.org/ 181 | [shields]: https://shields.io/ 182 | [thechangelog]: https://changelog.com/podcast/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](https://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/main/CHANGELOG.md 173 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md 174 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE 175 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/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]: https://semver.org/ 180 | [shields]: https://shields.io/ 181 | [thechangelog]: https://changelog.com/podcast/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](https://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/main/CHANGELOG.md 131 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md 132 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE 133 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/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]: https://semver.org/ 138 | [shields]: https://shields.io/ 139 | [thechangelog]: https://changelog.com/podcast/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é](https://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/main/CHANGELOG.md 167 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md 168 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE 169 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/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]: https://semver.org/ 174 | [shields]: https://shields.io/ 175 | [thechangelog]: https://changelog.com/podcast/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](https://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/main/CHANGELOG.md 173 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md 174 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE 175 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/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]: https://semver.org/ 180 | [shields]: https://shields.io/ 181 | [thechangelog]: https://changelog.com/podcast/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](https://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/main/CHANGELOG.md 168 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md 169 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE 170 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/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]: https://semver.org/ 175 | [shields]: https://shields.io/ 176 | [thechangelog]: https://changelog.com/podcast/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](https://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/main/CHANGELOG.md 177 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md 178 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE 179 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/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]: https://semver.org/ 184 | [shields]: https://shields.io/ 185 | [thechangelog]: https://changelog.com/podcast/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](https://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/main/CHANGELOG.md 135 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md 136 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE 137 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/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]: https://semver.org/ 142 | [shields]: https://shields.io/ 143 | [thechangelog]: https://changelog.com/podcast/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](https://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/main/CHANGELOG.md 166 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md 167 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE 168 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/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]: https://semver.org/ 173 | [shields]: https://shields.io/ 174 | [thechangelog]: https://changelog.com/podcast/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`.) Он международный, [рациональный](https://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/main/CHANGELOG.md 203 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md 204 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE 205 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/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]: https://semver.org/ 210 | [shields]: https://shields.io/ 211 | [thechangelog]: https://changelog.com/podcast/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](https://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/main/CHANGELOG.md 197 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md 198 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE 199 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/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]: https://semver.org/ 204 | [shields]: https://shields.io/ 205 | [thechangelog]: https://changelog.com/podcast/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](https://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/main/CHANGELOG.md 174 | [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md 175 | [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE 176 | [README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/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]: https://semver.org/ 181 | [shields]: https://shields.io/ 182 | [thechangelog]: https://changelog.com/podcast/127 183 | [vandamme]: https://github.com/tech-angels/vandamme/ 184 | --------------------------------------------------------------------------------