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

Improve commit log diffs section

Browse Source
This commit is contained in:
Olivier Lacan 2017-04-28 16:02:57 -07:00
parent 6a60ed5243
commit 69723cdea2
2 changed files with 22 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
CHANGELOG.md
View File

@ -24,6 +24,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
- Start versioning based on the current English version at 0.3.0 to help
translation authors keep things up-to-date.
- Rewrite "What makes unicorns cry?" section.
- Rewrite "Ignoring Deprecations" sub-section to clarify the ideal scenario.
- Improve "Commit log diffs" sub-section to further argument against them.
- Merge "Why can’t people just use a git log diff?" with "Commit log diffs"
- Fix typos in Simplified Chinese and Traditional Chinese translations.
- Fix typos in Brazilian Portugese translation.
- Fix typos in Turkish translation.

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

@ -68,12 +68,25 @@ version: 0.4.0
#### Commit log diffs
Just don’t do that, you’re helping nobody.
Using commit log diffs as changelogs is a bad idea: they're full of noise.
Things like merge commits, commits with obscure titles, documentation changes,
etc.
The purpose of a commit is to document a step in the evolution of the source
code. Some projects clean up commits, some don't.
The purpose of a changelog entry is to document the noteworthy difference,
often across multiple commits, to communicate them clearly to end users.
#### Ignoring Deprecations
When people upgrade from one version to another, it should be painfully clear
when something will break.
when something will break. It should be possible to upgrade to a version
that lists deprecations, remove what's deprecated, then upgrade to the version
where the deprecations become removals.
If you do nothing else, list deprecations, removals, and any breaking changes
in your changelog.
#### Confusing Dates
@ -104,26 +117,10 @@ version: 0.4.0
### 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.
Some projects also use `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc.
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?
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.
The purpose of a commit is to document one atomic step in the process by which
the code evolves from one state to another. The purpose of a changelog is to
document the noteworthy differences between these states.
As is the difference between good comments and the code itself,
so is the difference between a changelog and the commit log:
one describes the *why*, the other the how.
Call it `CHANGELOG.md`. Some projects use `HISTORY`, `NEWS`, or `RELEASES`.
While it's easy to think that the name of your changelog file doesn't matter
that much, why make it harder for your end users to consistently find notable
changes?
### Can changelogs be automatically parsed?
It’s difficult, because people follow wildly different formats and file names.