Skip to content

GitLab

Closed
Created by Michał Kępień@michalOwner

Replace the CHANGES file with a more practical alternative

I am creating this issue so that we can discuss whether we can come up with a usable alternative for maintaining the CHANGES file in the BIND 9 source repository.

This would really be a topic for an All Hands meeting, but it was raised often enough recently that it arguably should not wait until the next All Hands actually happens. Releasing BIND 9.18.0 sounds like a nice milestone at which we could change things.

Let's start with the pros:

  • CHANGES is a quick way for people not necessarily proficient with Git (support folks, users, etc.) to get a quick summary of what changed in a given BIND 9 release.1

  • CHANGES is trivial to search for keywords.

  • Each CHANGES entry is a unique2 identifier of a given set of changes across various BIND 9 branches.

Then, there are the cons:

  • These days, CHANGES entries are pretty much duplicates of commit log messages (which have become more verbose in the past months). However, they cannot be as long or as exhaustive as the latter, which necessitates edits/rewrites, which in certain cases causes a significant amount of time to be spent on making them legible and/or correct and/or precise (enough), both when merge requests are discussed and when monthly releases are prepared. As CHANGES has a more limited target audience than release notes, it does not necessarily feel like time well spent.

  • There are no strict rules governing what gets into CHANGES, in what form, and under what circumstances. We try to adhere to a rule of thumb which says that "anything that might be of interest to users and/or important to developers should be listed", but that turns out to be a very fuzzy line in practice.

  • Since the CHANGES file is under version control, all entries need to be cleaned up and prepared before any BIND 9 release is prepared. If a CHANGES tweak/fix/addition turns out to be necessary after a release is prepared, a respin is in order just to fix a text file.

  • CHANGES is generally a superset of release notes, which are supposed to list all important user-facing changes. However, the form and/or detail level of a given CHANGES entry often differs from its release notes counterpart. This means more duplicate work for every release.

Replacing CHANGES with some other solution acceptable by other ISC teams would allow SWENG to save time on discussing repeated/derivative texts, allowing us to spend that time on preparing accurate, verbose commit messages which are not limited to a few lines in size. It would also help avoid burning engineering time on silly stuff like retesting an entire release because of tweaks which do not affect the code itself or preparing & backporting missing CHANGES entries which were forgotten about (or consciously omitted) for random MRs.

  1. There is a a catch, though: adding a CHANGES entry for any given set of changes is not mandatory and therefore arbitrary in practice. Sometimes we list trivial stuff, sometimes we gloss over modifications which turn out to have critical consequences down the line, sometimes we spend time on arguing whether something needs to be listed or not. ↩

  2. Sometimes we assign different texts to the same entry. Example: entry 5712 in main vs. v9_16. ↩

Edited by Michał Kępień