From 69723cdea2904b394f023e1a720431d6a2b12013 Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Fri, 28 Apr 2017 16:02:57 -0700 Subject: [PATCH] Improve commit log diffs section --- CHANGELOG.md | 3 +++ source/en/0.4.0/index.html.haml | 41 +++++++++++++++------------------ 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7dbbb76..b6e5e74 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/source/en/0.4.0/index.html.haml b/source/en/0.4.0/index.html.haml index 9fd4221..100d540 100644 --- a/source/en/0.4.0/index.html.haml +++ b/source/en/0.4.0/index.html.haml @@ -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.