First release

[ScottFreeCode]

When reading through a change log, most of the changes have to be compared to the previous release. The first release, however, is different: there's nothing earlier to compare it to. Depending on the amount of stuff described in the change log for the initial release, it may be easy to see that the end of the log is below the entry before you start to read it, or it may not. I would suggest placing an "[Initial]" tag on the first release in the same position as the "[YANKED]" tag to help make it easier to switch focus from comparisons with previous versions to enumerating the base feature set; it's entirely redundant from a technical perspective, but from a human perspective it's a useful flag (and the technical redundancy makes it trivial to automatically add or correct).

(A question arises in the unlikely event that the first release ends up yanked: is the syntax "[YANKED] [Initial]"/"[Initial] [YANKED]" or is it "[Initial YANKED]"/"[YANKED, Initial]"...?)

Also, given the list of links at the bottom for the git comparisons of the releases, is there a good way to link to the first release? Is it preferred to omit it, to link to the release rather than to a comparison, or to link to a comparison of that release and the initial commit if possible, or something else?

[ScottFreeCode]

A reflection on the last question, after a little digging into my options: on GitHub I seem to be able to link to either the commit history leading up to the first release, or the view of the code at the point of the first release, or the release notes page for the first release. The closest thing to a comparison between releases is probably the commit history, but as the first part notes, the first release isn't really something to compare, but rather the start for comparisons; the code at that point in history is probably best.

[Nonibros]

I have to say that I agree with the initial tag.

[nbibler]

For initial releases, I generally link to the tree (source code at the point of that release), since there's nothing useful to compare it to. I can't say that I formally indicate an "initial" release in the heading, although I do usually note it in the notes for that version ("Initial public release" or something similar). Generally, the lowest number in the CHANGELOG is a fairly obvious initial release, especially if it's 1.0.

As for yanking, I think that's interesting. I haven't had to yank very often. I agree that yanked versions should be noted. But I would also go further to say that the changelog should explain why it was yanked. Ideally, if I'm the developer using the library and I'm running into a bug, it'd be ideal to see that the version I'm using was yanked because of something similar to the bug I'm experiencing and can expect to see it fixed in a later version.