Table of Contents
Back to agenda: https://gitlab.isc.org/isc-projects/bind9/-/wikis/BIND-9.19-Plan
Attendees: Matthijs, Vicky, Mark, Suzanne, Michał K., Petr, Artem, Aram, Cathy, Ondrej, Michal N., Chuck, Evan.
There are different views/opinions about the usefulness of CHANGES. See https://gitlab.isc.org/isc-projects/bind9/-/issues/2942 for a longer discussion.
Can we reach a rough consensus that some other mechanism can replace CHANGES?
How much should we care about the quality of CHANGES? Can it be considered an internal resource? Is a missing CHANGES entry a documentation bug?
Context: QA & Marketing spends hours each month polishing CHANGES, to ensure:
- correctness/accuracy
- completeness
- style
- formatting
- matching contents with corresponding release notes
Sometimes, ensuring the above requires going through an issue/MR and verifying that the entry matches the code changes.
Is this useful work? Is that time well spent?
Looking at others
How does Kea does it? Kea team drafts marketing-style release notes (which marketing edits) in a wiki page and then pastes change log entries below the "highlights". (So release notes INCLUDES the change log). There is no haggling or fine-tuning of the changelog itself, but if you really object to something in the changelog you can dress it up in the release note highlights. Link to the Rel Notes in the wiki is pasted into the repo tag for the release.
NSD and PowerDNS does both release notes and changes.
Unbound does just release notes and they are very terse (but with links to both issue and MR).
Knot resolver also has very terse release notes (stored on the release tags in the repo)no changes afaik.
Thoughts
Matthijs: "nice sweet spot" camp. would like to keep it, but doesn't understand why we care so much about the detail. I think QA can care a bit less about CHANGES.
Evan: agrees wrt level of detail
Ondrej: who are the "technical users" that cannot use Git?
Matthijs: It is just convenient to have a local file. Easy place to start looking.
Ondrej: What goes into CHANGES that cannot go into Release Notes?
Evan: Lots of example on the issue #2942 but another example: dispatch work - 30 commits, long verbose explanations, CHANGES is a concise summary; a summary CHANGES file is a good thing. It helps to get a rough idea of a time frame of a given change; likes the ordered nature and cross-branch nature; is often asked "why is BIND behaving this way?"
Suzanne: Why maintain it if it doesn't need to be the same quality as release notes?
Matthijs: Because it contains information that does not go into release notes.
Cathy: example from yesterday; frustrated because the CHANGES log didn't have a removal of build options by name (--enable-ipv6, --enable-threads) - GitLab didn't answer that directly
Ondrej: that's a great example of why CHANGES is broken; we have 3 sources of information (release notes, CHANGES, commit messages);
Matthijs: CHANGES is not perfect but easy start. If I can't find it there I can start looking into git. I don't think Cathy's example is a "great example of why CHANGES is broken", it is an incidental bad CHANGES entry.
Ondrej: we could try putting high-level information into the merge commit messages (GitLab feature)
Evan: we can start doing that, but we have 22 years of history done the other way
Ondrej: that's inertia, which we're trying to remove from the project.
Matthijs: likes the proposal of having the MR description being used to generate the CHANGES or a replacement file.
Vicky: also uses CHANGES a lot - people don't need to find the repo to get access to it; especially if you skip between a lot of versions while upgrading; Kea: the release notes are highlights, then they paste the change log underneath that
Ondrej: let's either do the release note or the CHANGES note; we currently have three "levels of abstraction".
Matthijs: disagrees with "either release notes or CHANGES"; the discussion shows they are not a substitute.
Evan: In the past, it wasn't SWENG's responsibility to write release notes - it was written by a technical editor or support, but that was hard to complete on time
Vicky: the reason we have this problem is we have 10 people writing stuff first and 2 people reviewing/reworking them at the end; strongly objects to hiring another person to write release notes; if we spent that much time on the ARM, that would be time better spent
Vicky: Compared to other open source vendors, our Release notes and CHANGES is like poetry. We do a pretty good job in this respect.
Cathy: We should set a minimum standard (for CHANGES and Release Notes)
Petr: Why can't we just append whatever all minor CHANGES to release notes?
Ondrej: agrees - one extra document we should get rid of.
Cathy: CHANGES goes all the way back to the beginning (Evan agrees).
Ondrej: But that's for historians, not software engineers; we need a single document for upgrading across multiple major versions.
Cathy: What if people need to jump multiple versions?
Ondrej: What if it has to be done in lockstep?
Petr: Why do we have a text file without any links to other parts of the documentation? that sounds like an outdated approach
Evan: Biggest irritation with writing CHANGES is the constant need to rebase because something has been merged in the meantime.
Ondrej: Can we drop the incremental numbering from the CHANGES?
Mark: There are issues in private. Also GitLab issues can cover multiple MRs.
Matthijs, Evan: Both don't have an issue with dropping the incremental numbering.
Takeaways
Treat CHANGES more lightweight.
We can research generate the CHANGES file.