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. AsCHANGES
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 aCHANGES
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 givenCHANGES
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.
-
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.↩ -
Sometimes we assign different texts to the same entry. Example: entry 5712 in
main
vs.v9_16
.↩