Rewrite "What makes unicorns cry?”

Gah, this section sucked. Broke it down into multiple sub-sections
instead of a list.
This commit is contained in:
Olivier Lacan 2017-04-27 12:18:38 -07:00
parent 7af2d256ea
commit 68714f8946
2 changed files with 27 additions and 15 deletions

View File

@ -6,6 +6,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
## [Unreleased]
### Added
- "Why keep a changelog?" section
- "Who needs a changelog?" section
- "How do I make a changelog?" section
- Simplified and Traditional Chinese translations from @tianshuo.
- German translation from @mpbzh.
- Italian translation from @roalz.
@ -19,6 +22,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
- Start using "changelog" over "change log" since it's the common usage.
- 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.
- Fix typos in Simplified Chinese and Traditional Chinese translations.
- Fix typos in Brazilian Portugese translation.
- Fix typos in Turkish translation.
@ -27,6 +31,8 @@ translation authors keep things up-to-date.
- Improve phrasing in French translation.
- Fix phrasing and spelling in German translation.
### Removed
- Section about "changelog" vs "CHANGELOG".
## [0.3.0] - 2015-12-03
### Added

View File

@ -65,24 +65,30 @@ version: 0.4.0
- People can see what changes they might expect in upcoming releases
- At release time, you just have to change `"Unreleased"` to the version number
and add a new `"Unreleased"` header at the top.
### Can a changelog be bad?
### What makes unicorns cry?
Alright…lets get into it.
Yes, and this is how changelogs can hurt more than help:
- **Dumping a diff of commit logs.** Just dont do that, youre helping nobody.
- **Not emphasizing deprecations.** When people upgrade from one version to
another, it should be painfully clear when something will break.
- **Dates in region-specific formats.** In the U.S., people put the month first
("06-02-2012" for June 2nd, 2012, which makes *no* sense), while many people
in the rest of the world write a robotic-looking "2 June 2012", yet pronounce
it differently. "2012-06-02" works logically from largest to smallest, doesn't
overlap in ambiguous ways with other date formats, and is an
[ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Thus, it
is the recommended date format for changelogs.
#### Commit log diffs
Theres more. Help me collect those unicorn tears by
[opening an issue][issues]
or a pull request.
Just dont do that, youre helping nobody.
#### Ignoring Deprecations
When people upgrade from one version to another, it should be painfully clear
when something will break.
#### Confusing Dates
In the U.S., people put the month first ("06-02-2012" for June 2nd, 2012,
which makes *no* sense), while many people in the rest of the world write a
robotic-looking "2 June 2012", yet pronounce it differently. "2012-06-02"
works logically from largest to smallest, doesn't overlap in ambiguous ways
with other date formats, and is an [ISO standard][iso]. Thus, it is the
recommended date format for changelogs.
Theres more. Help me collect those unicorn tears by [opening an
issue][issues] or a pull request.
### Is there a standard changelog format?
Sadly, no. Calm down. I know you're furiously rushing to find that link