tyler.durden/keep-a-changelog
1
0
Fork 0
mirror of https://github.com/olivierlacan/keep-a-changelog.git synced 2025-07-29 16:54:12 +02:00
Code Issues Packages Projects Releases Wiki Activity

Clarify guiding principles & types

Browse Source
This commit is contained in:
Olivier Lacan 2017-04-27 12:19:17 -07:00
parent 68714f8946
commit bc8d9993d4
2 changed files with 16 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGELOG.md
View File

@ -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.

33
source/en/0.4.0/index.html.haml
View File

@ -34,28 +34,25 @@ version: 0.4.0
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
#### 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.