see git log
(This automatically-replaced single-entry is used for frequent
updates in the unstable development series of releases.
A properly constructed changelog entry is a requirement
for stable releases.)
At the bottom of the source file there are some entries that are not visible in the rendered page, but are essential for the version links to the GitLab commit comparisons to work:
Yes, I meant to write something about it here, but it was way past bedtime. Your suggestion LGTM. Perhaps with the clarification that the user in this case also includes a user who wants to build the software, but not us maintainers per se. E.g. stuff that relates only to the CI pipeline does not end up there. My reasoning is that the changelog must be short enough to be useful to external users. More hard-core users, such as maintainers and even contributors are expected to use be able to use commit messages, issues and merge requests.
As an example, when I rewrote the latest release, I removed references to my Docker image merge requests since Docker images are not (yet anyway) part of the “product”. I also removed references to modifications of the CI/CD pipeline and redundant merge requests, i.e. those that fixed an issue for which the issue itself was mentioned.
Does this sound like the correct intuition? I deliberately picked two changes that are pretty close together in terms of what type of “user” is likely to see the impact.
Changes deserve a changelog entry if they impact (1) or (2) or both. Changes can be omitted from the changelog if they only impact (3), who can get their knowledge from the commit log. Do I have that right?
Yes, that’s an accurate interpretation of what I meant, but I’m definitely open to discuss it.
You forgot two user categories:
0a. end user using Graphviz without knowing how they got it.
0b. end user using Graphviz without knowing it (probably as part of another application)
Somewhat meant as a joke, but when talking about users, it’s important to talk also about what they are using: the DOT language, the CLI tools, the binaries, the installers, the build system, the source code, the commits, the merge requests, the issues, the test results, the GitLab meta-data etc.
Since we intend to maintain only one changelog, we must draw the line somewhere.
To elaborate further on what (I think) should and should not go into the changelog:
#1737 should go into the changelog, since it’s a problem that was present in the latest release.
#1735 should not go into the changelog, since it’s a problem that wasn’t present in the latest release. No user of the released versions (binaries or portable source) have had a chance to be hit by it and users building the software from HEAD are expected to keep track of issues and commits themselves.
I like the part about people using Graphviz without knowing where they got it, or that they are even using it.
In general the recommendations are sound or at least introduce a higher level of rigor than we have had lately (with the possible exception of John Ellson who is more clueful about software maintenance processes).
All of this is inherently uncertain because I don’t know what timezone some of the timestamps are in relation to. However, if I had to guess I would say Stephen likely had no idea this had even been filed as a CVE at the time he made the fix (feel free to contradict me, Stephen). Loginsoft make no mention of it on the Gitlab issue.
My point here is that, as long as we are not actively requesting CVEs ourselves, we are never going to be able to tell when we fix one. A third party can even retroactively request a CVE for something we fixed in a previous release. Large software orgs like Google, purveyor of our friendly Google Autofuzz bot, serve as their own CVE Numbering Authority. They are assigned a block of CVEs and often have allocated one to an internal issue they are tracking but have not yet broadcast the allocation.
tl;dr: I think we can do best-effort, but the changelog is never going to be authoritative with respect to CVEs.
I think usually security shops should tell us of the CVE. It’s a shame that didn’t happen here, but I’m still glad they reported it. I wonder if there’s some way for us to subscribe to CVEs being reported for graphviz. As you say, we can start by including the ones we do know about.
I think we need to change our decision on this. The specific example I previously gave of the ps2pdf change that didn’t deserve a change log entry has caused a lot of disruption to users (e.g. #1763, homebrew-core!57132, linuxbrew-core!20812, …). It’s becoming clear to me that we have a significant group of users who are building Graphviz from source, but also not monitoring Graphviz commits.
I propose we reverse our stance on changes that only affect people building from source and do include changelog entries for these.
