diff --git a/CHANGELOG.md b/CHANGELOG.md index aeb0fa5..7dbbb76 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/). - "Why keep a changelog?" section - "Who needs a changelog?" section - "How do I make a changelog?" section +- New "Guiding Principles" sub-section to "How do I make a changelog?". - Simplified and Traditional Chinese translations from @tianshuo. - German translation from @mpbzh. - Italian translation from @roalz. diff --git a/source/en/0.4.0/index.html.haml b/source/en/0.4.0/index.html.haml index 85d7558..c62ff17 100644 --- a/source/en/0.4.0/index.html.haml +++ b/source/en/0.4.0/index.html.haml @@ -34,28 +34,25 @@ version: 0.4.0
#{File.read("CHANGELOG.md")}+ #### Guiding Principles + - Changelogs are *for humans*, not machines. + - There should be an entry for every single version. + - The same [types of changes](#types-of-changes) should be grouped. + - Versions and sections should be linkable. + - The latest version comes first. + - The release date of each versions is displayed. + - Mention if the project follows [Semantic Versioning][semver]. + ##### Types of changes + - `Added` for new features. + - `Changed` for changes in existing functionality. + - `Deprecated` for once-stable features removed in upcoming releases. + - `Removed` for deprecated features removed in this release. + - `Fixed` for any bug fixes. + - `Security` to invite users to upgrade in case of vulnerabilities. - A good changelog sticks to these principles: - - - It’s made for humans, not machines, so legibility is crucial. - - Easy to link to any section (hence Markdown over plain text). - - One sub-section per version. - - List releases in reverse-chronological order (newest on top). - - Write all dates in `YYYY-MM-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) It’s international, [sensible](http://xkcd.com/1179/), and language-independent. - - Explicitly mention whether the project follows [Semantic Versioning][semver]. - - Each version should: - - List its release date in the above format. - - Group changes to describe their impact on the project, as follows: - - `Added` for new features. - - `Changed` for changes in existing functionality. - - `Deprecated` for once-stable features removed in upcoming releases. - - `Removed` for deprecated features removed in this release. - - `Fixed` for any bug fixes. - - `Security` to invite users to upgrade in case of vulnerabilities. - ### How can I minimize the effort required? Always have an `"Unreleased"` section at the top for keeping track of any changes.