Clarify release notes vs. changelog workflow
Here’s some feedback produced while preparing the 2.10 release notes since sajolida was away.
Some “external” changelogs are handled in
contribute/how/documentation/release_notes.mdwn, while some are
handled in the part of the release process that’s about updating our
changelog. I’m confused: this means that potentially, some changes may
end up being documented in the release notes, but not in the changelog.
Same for “Analyze the diff of packages”. Of course, in some way it makes
sense (the changelog just states some raw facts like “upgraded Tor to
X.Y”, while the release notes have to explain the impact on users, so in
practice the release notes are not a strict subset of info that’s
already in the changelog). But then, if we think the release notes
writer must read all these changelogs, to be consistent, they must also
read the changelogs of our custom software we install as .deb:s, no? I
don’t know how we can handle this best.
Also, there seems to be some duplication between both checklists, e.g. “the Redmine view for this release” vs. “the ”Fix committed" section on the *Release Manager View". I don’t understand why.
These are just examples, I’m not going to build a complete list of things that might be a problem. What I mean here is that it seems clear to me that the release notes vs. changelog writing processes probably need to get to know each other better, in order to split the work better, produce higher quality change documentation, and avoid duplicated work.
I’m assigning this to sajolida to start with, since he wrote the release notes checklist after we created the changelog one.
Related issues
- Blocks #14758 (closed)
Original created by @intrigeri on 12167 (Redmine)