💾 Archived View for thrig.me › blog › 2024 › 08 › 29 › changelog.gmi captured on 2024-08-31 at 12:51:31. Gemini links have been rewritten to link to archived content
-=-=-=-=-=-=-
Here's the release notes (or changelog) for some random piece of software:
See the git repository.
What to discuss? Some developers will be lazy, and will not maintain a changelog, or if there is one, it will simply mention to go look at CVS or Fossil or whatever as shown by the line above. I've certainly been guilty of this, usually in smaller repositories where there is not much to summarize. There can be advantages to not maintained a changelog, as one need not spend time summarizing the repository changes into a changelog or release notes file, and repository tools (if you know how to use them) offer selection by date ranges, branch, etc. Disadvantages are that folks may need to download a whole repository, or to learn some web interface, just to find out what changed in the latest release. This is perhaps similar to speaking where the audience may want more or different detail, while the speaker may not want to say all that, especially if documenting things is not really a skill they have developed.
Probably the easiest way to maintain a changelog is to keep an eye on the changes as they trickle in, take notes, then review and cleanup the list come release time. Going back through the repository logs and mailing lists and whatnot close to release time is another approach, but might easily miss something important that was done who knows how many months before the release. Best to have someone keep notes as things trundle along.
Or you could avoid duplicating work, not make a summarizing changelog, and point folks at the repository logs. This may be more useful if care is taken to squash branches or whatnot to present a good history. Not all repositories can or want to do that, as this may mangle or hide various details.
The OpenBSD changelog is pretty long, though learning how to skim for the interesting or relevant bits is a skill you could work on. Another method is to wait for a discussion channel to mention neat new things, but in that case you'll only learn about what those folks think is important. Still, a community filter can be pretty good at surfacing important things.