Changelog is one year behind

[Vlad-Shcherbina]

The latest version on crates.io is 1.3.4 (Feb 7, 2020), but the CHANGELOG.md only lists 1.3.0 (Jan 19, 2019).

1.3.1 - internal changes 1.3.2 - adds ReadBytesExt::read_i8_into() + internal changes 1.3.3 - adds ByteOrder::write_i8_into() + internal 1.3.4 - trivial

Even if the change is trivial, it's worth mentioning in the changelog that it's trivial.

[BurntSushi]

I'm inclined to remove the changelog. As can be seen, it is very easy to forget. And I question its value for a project that has as low activity as this one. (Instead, the commit log should be a fine substitute.)

[Vlad-Shcherbina]

I'm against removing the existing changelog. There are projects with pinned old dependencies, and not having a changelog in an obvious place (nobody would guess to look for it among deleted files in version history) would make it harder to assess if upgrading makes sense.

If you mean stop maintaining the changelog, sure. It's a cost-benefit thing, and your position makes sense. Consider adding a note at the top that trivial releases will not be mentioned there from now on.

---

What follows is explicitly just my subjective opinion, I'm not pushing for anything, feel free to ignore.

1. Not forgetting to update the changelog is still important for breaking changes. Practicing not forgetting always helps not forgetting when it matters.
2. It's a good idea to have a release checklist anyway (to avoid forgetting to publish to crates.io, to add git tag, to build documentation and check it for broken links, etc.), and "update the changelog" could be another entry in this checklist.
3. It's easier to maintain a changelog if there is an "unreleased" section that is updated at the time of change. At the time of release "unreleased" is simply promoted to "x.y.z", and new empty "unreleased" is added.
4. Commit history is likely to contain everything that should be in the changelog, but it also has plenty of noise, so it's more effort to read. It is also immutable-ish, a commit message can't be reworded if it turned out it's confusing.
5. The value of the changelog is mostly in the chance that it will help dealing with some problem on upgrade. This is proportional to the rate of change. But the effort to keep the changelog is also proportional to the rate of change. ROI is kind of the same even for low-activity projects.

[BurntSushi]

Yes. This isn't my first rodeo. I understand and employ your suggestions in a variety of contexts. I just can't do it for every single one of the dozens of crates that I maintain. It's too much work. In the case of byteorder, it evolves extremely slowly and is pretty unlikely to ever see another breaking change at this point. Combine that with the simplicity of byteorder itself, my feeling is that reading the commits is probably good enough. The generic advice prescribed by keepachangelog is something I agree with generally, but that doesn't mean it's actually a bad practice 100% of the time.

I'll noodle on this and, if I remember, make a decision when I do the next release.

It's a good idea to have a release checklist anyway (to avoid forgetting to publish to crates.io, to add git tag, to build documentation and check it for broken links, etc.), and "update the changelog" could be another entry in this checklist.

I automate this as much as possible. e.g., Scripts to deal with version numbers, crate pushes and git tags.

[Vlad-Shcherbina]

Then it could be echo "Remember the changelog!" (or perhaps even checking if the changelog was modified since last release, but that's error-prone). Ok I'm shutting up now.

[darxriggs]

Another option could be to use a solution like https://github.com/release-drafter/release-drafter.