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:
parent
7af2d256ea
commit
68714f8946
|
@ -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
|
||||
|
|
|
@ -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…let’s get into it.
|
||||
Yes, and this is how changelogs can hurt more than help:
|
||||
|
||||
- **Dumping a diff of commit logs.** Just don’t do that, you’re 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
|
||||
|
||||
There’s more. Help me collect those unicorn tears by
|
||||
[opening an issue][issues]
|
||||
or a pull request.
|
||||
Just don’t do that, you’re 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.
|
||||
|
||||
There’s 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
|
||||
|
|
Loading…
Reference in New Issue