From d63e8258bc721909ddb709371c41c0a1fd22a105 Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Sun, 31 Aug 2014 21:58:59 -0400 Subject: [PATCH] Some changes to sections and references. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Including sections with no notables changes by putting a single "- Nothing." entry was a bad idea because for every single release this created a ton of noise. My only gripe with this decision is that users now have to assume that — for instance — the "Deprecated" section was intentionally left out because it contained nothing, while it's quite possible that they maintainers may not have deemed deprecations worthy of a change log entry. That's a problem because it makes expectations hard to manage. Another change I've made is that I now refer to a "change log" (lower case, two words) instead of a "CHANGELOG" (uppercase, one word) because I've released that the file is named "CHANGELOG" but the purpose of the file matters more than its name. Moreover the previous spelling made for awkward sentences and style. --- CHANGELOG.md | 45 +++++++++++++-------------------------------- index.html | 27 ++++++++++++++------------- 2 files changed, 27 insertions(+), 45 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f193150e..0ef1b88c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,49 +1,30 @@ -# Changelog +# Change Log All notable changes to this project will be documented in this file. -## 0.0.3 - 2014-08-09 - -### Added -- "Why should I care?" section mentioning The Changelog podcast. - -### Deprecated -- Nothing. +## 0.0.4 - 2014-08-09 +### Changed +- Refer to a "change log" instead of a "CHANGELOG" throughout the site +to differentiate between the file and the purpose of the file — the +logging of changes. ### Removed -- Nothing. +- Remove empty sections from CHANGELOG, they occupy too much space and +create too much noise in the file. People will have to assume that the +missing sections were intentionally left out because they contained no +notable changes. -### Fixed -- Nothing. +## 0.0.3 - 2014-08-09 +### Added +- "Why should I care?" section mentioning The Changelog podcast. ## 0.0.2 - 2014-07-10 - ### Added - Explanation of the recommended reverse chronological release ordering. -### Deprecated -- Nothing. - -### Removed -- Nothing. - -### Fixed -- Nothing. - - ## 0.0.1 - 2014-05-31 - ### Added - This CHANGELOG file to hopefully serve as an evolving example of a standardized open source project CHANGELOG. - CNAME file to enable GitHub Pages custom domain - README now contains answers to common questions about CHANGELOGs - Good examples and basic guidelines, including proper date formatting. - Counter-examples: "What makes unicorns cry?" - -### Deprecated -- Nothing. - -### Removed -- Nothing. - -### Fixed -- Nothing. diff --git a/index.html b/index.html index 029d314b..92cc2afa 100644 --- a/index.html +++ b/index.html @@ -25,34 +25,35 @@

Why should I care?

(fitting, right?) podcast about why open source maintainers and contributors should care, and the motivations behind this project. If you can spare the time (1:06), it’s a good listen.

-

What makes up a good CHANGELOG?

-

I’m glad you asked.

+

What makes a good CHANGELOG?

+

I’m glad you asked.

+

A good CHANGELOG sticks to these principles:

-

It’s also good to explicitly mention whether the project follows Semantic Versioning.

How can I minimize the effort required?

-

Always have an "Unreleased" section at the top for keeping notes on any +

Always have an "Unreleased" section at the top for keeping track of any changes.

This serves two purposes:

What makes unicorns cry?

Alright…let’s get into it.