forked from olivierlacan/keep-a-changelog
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html.haml
183 lines (145 loc) · 8.32 KB
/
index.html.haml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
---
description: Keep a Changelog
title: Keep a Changelog
language: en
version: 0.3.0
---
:markdown
# Keep a CHANGELOG
## Don’t let your friends dump git logs into CHANGELOGs™
Version **#{current_page.metadata[:page][:version]}**
### What’s a change log?
A change log is a file which contains a curated, chronologically ordered
list of notable changes for each version of a project.
%pre.changelog= File.read("CHANGELOG.md")
:markdown
### What’s the point of a change log?
To make it easier for users and contributors to see precisely what
notable changes have been made between each release (or version) of the project.
### Why should I care?
Because software tools are for people. If you don’t care, why are
you contributing to open source? Surely, there must be a kernel (ha!)
of care somewhere in that lovely little brain of yours.
I [talked with Adam Stacoviak and Jerod Santo on The Changelog][thechangelog]
(fitting, right?) podcast about why 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 a good change log?
I’m glad you asked.
A good change log sticks to these principles:
- It’s made for humans, not machines, so legibility is crucial.
- Easy to link to any section (hence Markdown over plain text).
- One sub-section per version.
- List releases in reverse-chronological order (newest on top).
- Write all dates in `YYYY-MM-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) It’s international, [sensible](http://xkcd.com/1179/), and language-independent.
- Explicitly mention whether the project follows [Semantic Versioning][semver].
- Each version should:
- List its release date in the above format.
- Group changes to describe their impact on the project, as follows:
- `Added` for new features.
- `Changed` for changes in existing functionality.
- `Deprecated` for once-stable features removed in upcoming releases.
- `Removed` for deprecated features removed in this release.
- `Fixed` for any bug fixes.
- `Security` to invite users to upgrade in case of vulnerabilities.
### How can I minimize the effort required?
Always have an `"Unreleased"` section at the top for keeping track of any
changes.
This serves two purposes:
- 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.
### What makes unicorns cry?
Alright…let’s get into it.
- **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 change logs.
There’s more. Help me collect those unicorn tears by
[opening an issue][issues]
or a pull request.
### Is there a standard change log format?
Sadly, no. Calm down. I know you're furiously rushing to find that link
to the GNU change log style guide, or the two-paragraph GNU NEWS file
"guideline". The GNU style guide is a nice start but it is sadly naive.
There's nothing wrong with being naive but when people need
guidance it's rarely very helpful. Especially when there are many
situations and edge cases to deal with.
This project [contains what I hope will become a better CHANGELOG file convention][CHANGELOG].
I don't think the status quo is good enough, and I think that as a community we
can come up with better conventions if we try to extract good practices from
real software projects. Please take a look around and remember that
[discussions and suggestions for improvements are welcome][issues]!
### What should the change log 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
change log 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 change log 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 change log and the commit log:
one describes the *why*, the other the how.
### Can change logs be automatically parsed?
It’s difficult, because people follow wildly different formats and file names.
[Vandamme][vandamme] is a Ruby gem
created by the [Gemnasium][gemnasium] team and which parses
many (but not all) open source project change logs.
### Why do you alternate between spelling it "CHANGELOG" and "change log"?
"CHANGELOG" is the name of the file itself. It's a bit shouty but it's a
historical convention followed by many open source projects. Other
examples of similar files include [`README`][README], [`LICENSE`][LICENSE],
and [`CONTRIBUTING`][CONTRIBUTING].
The uppercase naming (which in old operating systems made these files stick
to the top) is used to draw attention to them. Since they're important
metadata about the project, they could be useful to anyone intending to use
or contribute to it, much like [open source project badges][shields].
When I refer to a "change log", I'm talking about the function of this
file: to log changes.
### What about yanked releases?
Yanked releases are versions that had to be pulled because of a serious
bug or security issue. Often these versions don't even appear in change
logs. They should. This is how you should display them:
`## 0.0.5 - 2014-12-13 [YANKED]`
The `[YANKED]` tag is loud for a reason. It's important for people to
notice it. Since it's surrounded by brackets it's also easier to parse
programmatically.
### Should you ever rewrite a change log?
Sure. There are always good reasons to improve a change log. I regularly open
pull requests to add missing releases to open source projects with unmaintained
change logs.
It's also possible you may discover that you forgot to address a breaking change
in the notes for a version. It's obviously important for you to update your
change log in this case.
### How can I contribute?
This document is not the **truth**; it’s my carefully considered
opinion, along with information and examples I gathered.
Although I provide an actual [CHANGELOG][] on [the GitHub repo][gh],
I have purposefully not created a proper *release* or clear list of rules
to follow (as [SemVer.org][semver] does, for instance).
This is because I want our community to reach a consensus. I believe the
discussion is as important as the end result.
So please [**pitch in**][gh].
[CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
[CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md
[LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE
[README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md
[gemnasium]: https://gemnasium.com/
[gh]: https://github.com/olivierlacan/keep-a-changelog
[issues]: https://github.com/olivierlacan/keep-a-changelog/issues
[semver]: http://semver.org/
[shields]: http://shields.io/
[thechangelog]: http://5by5.tv/changelog/127
[vandamme]: https://github.com/tech-angels/vandamme/