I used to refer exclusively to a "CHANGELOG" instead of a much more
elegant "change log", so I expanded the section about naming to
explain the difference and add a bit of historical information about
why these files are so shouty.
The static image was a stop-gap to give people a visual rendition of a
raw CHANGELOG file. I find this iframe solution much more satisfying
because it allows people to scroll around the CHANGELOG file.
It's also a LOT easier to maintain since... I don't have to update the
image ever again. Wee!
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.
- Reordered bullets to go from general ▶︎ specific (that is, overall/document guidelines ▶︎ per-version guidelines)
- Edited phrasing of bullets for clarity (and a slightly more “instructions”- or “checklist”-like tone)
Why?
- smart quotes are prettier
- they also read easier
- the document was using a mix of smart- and straight-quotes anyway
- (It doesn’t matter in this document, but…) in documents with code examples, smart quotes in comments and body text keep text editors from confusing them with quotes in code
- smart quotes add polish (and credibility)—important for “call to action” documents like this ☺
I figured adding this section was notable enough to make a new
CHANGELOG entry as well.
The podcast is a bit long so I don't expect people new to this project
to actually listen to it right away but it would be good to extract
some of the good points made on the show into more fuel to the fire.
