diff --git a/source/en/0.4.0/index.html.haml b/source/en/0.4.0/index.html.haml index c62ff17..9fd4221 100644 --- a/source/en/0.4.0/index.html.haml +++ b/source/en/0.4.0/index.html.haml @@ -52,16 +52,16 @@ version: 0.4.0 - `Fixed` for any bug fixes. - `Security` to invite users to upgrade in case of vulnerabilities. + ### How can I reduce the effort required to maintain a changelog? - ### How can I minimize the effort required? - Always have an `"Unreleased"` section at the top for keeping track of any - changes. + Keep an `"Unreleased"` section at the top for keeping track of any changes. This serves two purposes: - People can see what changes they might expect in upcoming releases - - At release time, you just have to change `"Unreleased"` to the version number - and add a new `"Unreleased"` header at the top. + - At release time, you can convert `"Unreleased"` to the version's release + number and add a new `"Unreleased"` header at the top. + ### Can a changelog be bad? Yes, and this is how changelogs can hurt more than help: @@ -88,20 +88,22 @@ version: 0.4.0 issue][issues] or a pull request. ### Is there a standard changelog format? - Sadly, no. Calm down. I know you're furiously rushing to find that link - to the GNU changelog style guide, or the two-paragraph GNU NEWS file - "guideline". The GNU style guide is a nice start but it is sadly naive. - There's nothing wrong with being naive but when people need - guidance it's rarely very helpful. Especially when there are many - situations and edge cases to deal with. - This project [contains what I hope will become a better CHANGELOG file convention][CHANGELOG]. - I don't think the status quo is good enough, and I think that as a community we - can come up with better conventions if we try to extract good practices from - real software projects. Please take a look around and remember that - [discussions and suggestions for improvements are welcome][issues]! + Sadly, no. Calm down. I know you're furiously rushing to find that link to the + GNU changelog style guide, or the two-paragraph GNU NEWS file "guideline". The + GNU style guide is a nice start but it is sadly naive. There's nothing wrong + with being naive but when people need guidance it's rarely very helpful. + Especially when there are many situations and edge cases to deal with. + + This project [contains what I hope will become a better CHANGELOG file + convention][CHANGELOG]. I don't think the status quo is good enough, and I + think that as a community we can come up with better conventions if we try to + extract good practices from real software projects. Please take a look around + and remember that [discussions and suggestions for improvements are + welcome][issues]! ### What should the changelog file be named? + Well, if you can’t tell from the example above, `CHANGELOG.md` is the best convention so far. @@ -110,7 +112,8 @@ version: 0.4.0 It’s a mess. All these names only makes it harder for people to find it. - ### Why can’t people just use a `git log` diff? + ### Why can’t people just use a git log diff? + Because log diffs are full of noise — by nature. They could not make a suitable changelog even in a hypothetical project run by perfect humans who never make typos, never forget to commit new files, never miss any part of a refactoring. @@ -161,6 +164,13 @@ version: 0.4.0 So please [**pitch in**][gh]. + ### Press + + I [talked with Adam Stacoviak and Jerod Santo on The Changelog][thechangelog] + (fitting, right?) podcast about why maintainers and + contributors should care, and the motivations behind this project. + If you can spare the time (1:06), it’s a good listen. + [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE @@ -172,3 +182,4 @@ version: 0.4.0 [shields]: http://shields.io/ [thechangelog]: http://5by5.tv/changelog/127 [vandamme]: https://github.com/tech-angels/vandamme/ + [iso]: http://www.iso.org/iso/home/standards/iso8601.htm