Feature #12167
Clarify release notes vs. changelog workflow
100%
Description
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.
Subtasks
Related issues
|
Blocks Tails - |
Resolved | 2017-09-17 |
History
#1 Updated by intrigeri 2017-01-23 19:00:27
Actually, some parts (“the diff of packages”, reading some changelogs like the one for I2P, Electrum, Torbirdy and Icedove) seem to have a huge cost/benefit ratio. It’s nice if writers fancy going that far, so maybe they can stay in that checklist, but seriously, I’m not sure they should be on the technical writer’s plate formally speaking. I’ll personally skip them.
#2 Updated by sajolida 2017-10-16 14:15:34
- blocks Feature #14760: Adjust doc for Wayland: starting graphical applications as root added
#3 Updated by sajolida 2017-10-16 14:16:14
- blocked by deleted (
Feature #14760: Adjust doc for Wayland: starting graphical applications as root)
#4 Updated by sajolida 2017-10-16 14:16:28
- blocks
Feature #14758: Core work 2017Q4 → 2018Q1: Technical writing added
#5 Updated by sajolida 2018-02-24 13:18:02
- Assignee changed from sajolida to intrigeri
> I’m confused: this means that potentially, some changes may end up being documented in the release notes, but not in the changelog.
I also sometimes add missing stuff to the changelog, about once every year. See 89b04e5fd2 and 8f2fd3cc94.
> 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).
I like having links to upstream changelog (eg. Electrum) in my template because that’s where I need them in case I want to point to it.
For example, Electrum was updated in Tails 2.6 but it was not mentioned in the changelog. I don’t know why, maybe because the update was not fixing any bug that was reported on our Redmine. Still, I felt it was worth mentioning in our release notes and pointing to the changelog, even if nothing in there was worth mentioning explicitly in our release notes (and 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.
Until now I was taking for granted that the relevant changes to our custom software would also be in the changelog (or the Redmine view). At least because they would correspond to a ticket in Redmine.
> 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.
I could remove checking Redmine but then I wouldn’t be able to spot missing bits in the Changelog anymore. How is the changelog reviewed otherwise?
> 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 read the “Changelog” section of the release process and the two duplicates bits of work that I could spot are:
- Checking Redmine, which is what allows me to spot missing bits. But maybe it’s not worth it.
- Checking the diff of packages. It’s not clear from the release process, which packages will be mentioned in the changelog. I could drop that part if the release process specified that it should list all updates to applications that’s listed in /doc/about/features.
> Actually, some parts (“the diff of packages”, reading some changelogs like the one for I2P, Electrum, Torbirdy and Icedove) seem to have a huge cost/benefit ratio. It’s nice if writers fancy going that far, so maybe they can stay in that checklist, but seriously, I’m not sure they should be on the technical writer’s plate formally speaking. I’ll personally skip them.
Done in b72d2226ff. Note that it only makes sense to read these changelogs if the applications gets updated, which is really not very often in the case of Tails. I’m not reading all these changelogs every time!!!
#6 Updated by sajolida 2018-02-24 13:49:30
Sorry, I mean in 811c251b0c.
#7 Updated by intrigeri 2018-02-24 14:08:58
- Assignee changed from intrigeri to sajolida
- QA Check set to Info Needed
>> 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).
> I like having links to upstream changelog (eg. Electrum) in my template because that’s where I need them in case I want to point to it.
> For example, Electrum was updated in Tails 2.6 but it was not mentioned in the changelog. I don’t know why, maybe because the update was not fixing any bug that was reported on our Redmine. Still, I felt it was worth mentioning in our release notes and pointing to the changelog, even if nothing in there was worth mentioning explicitly in our release notes (and changelog).
OK.
>> 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.
> Until now I was taking for granted that the relevant changes to our custom software would also be in the changelog (or the Redmine view). At least because they would correspond to a ticket in Redmine.
Right, makes sense to me!
>> 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.
> I could remove checking Redmine but then I wouldn’t be able to spot missing bits in the Changelog anymore.
I’m not convinced that adding a missing bit in the changelog about once a year is worth doing this extra work for every release. If someone feels like doing it, fine with me, but I personally would not consider that task as important enough to qualify as Core work.
> How is the changelog reviewed otherwise?
Our Benevolent Control Freak for Life™ (that’s me) looks at the changelog entry when he’s around at the right time. I occasionally fix some stuff in there, either before the release or after. But AFAIK nobody checks that nothing is missing in the changelog.
>> 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 read the “Changelog” section of the release process and the two duplicates bits of work that I could spot are:
> * Checking Redmine, which is what allows me to spot missing bits. But maybe it’s not worth it.
Not worth it IMO.
> * Checking the diff of packages. It’s not clear from the release process, which packages will be mentioned in the changelog. I could drop that part if the release process specified that it should list all updates to applications that’s listed in /doc/about/features.
Agreed modulo I would replace “all updates” with “all updates to a new upstream release”. Anything else is unlikely to be user-visible so the marginal cost / marginal benefit ratio seems to be huge except for new upstream releases.
Shall I document this?
>> Actually, some parts (“the diff of packages”, reading some changelogs like the one for I2P, Electrum, Torbirdy and Icedove) seem to have a huge cost/benefit ratio. It’s nice if writers fancy going that far, so maybe they can stay in that checklist, but seriously, I’m not sure they should be on the technical writer’s plate formally speaking. I’ll personally skip them.
> Done in 811c251b0c. Note that it only makes sense to read these changelogs if the applications gets updated, which is really not very often in the case of Tails.
Same as above, with s/was updated/was updated to a new upstream release/ I would totally agree. If you agree I’ll apply this change at the same time as the release process doc proposed above.
> I’m not reading all these changelogs every time!!!
Cool.
#8 Updated by sajolida 2018-03-02 20:38:36
>> * Checking Redmine, which is what allows me to spot missing bits. But maybe it’s not worth it.
>
> Not worth it IMO.
I removed that line with 65aa66d445.
>> * Checking the diff of packages. It’s not clear from the release process, which packages will be mentioned in the changelog. I could drop that part if the release process specified that it should list all updates to applications that’s listed in /doc/about/features.
>
> Agreed modulo I would replace “all updates” with “all updates to a new upstream release”. Anything else is unlikely to be user-visible so the marginal cost / marginal benefit ratio seems to be huge except for new upstream releases.
>
> Shall I document this?
Yeap.
> Same as above, with s/was updated/was updated to a new upstream release/ I would totally agree.
For me that was implicit…
> If you agree I’ll apply this change at the same time as the release process doc proposed above.
I already did that in c2cf179908.
#9 Updated by sajolida 2018-03-02 20:38:55
- Assignee changed from sajolida to intrigeri
- QA Check changed from Info Needed to Dev Needed
#10 Updated by intrigeri 2018-03-04 07:47:57
- Status changed from Confirmed to In Progress
- Target version set to Tails_3.7
- % Done changed from 0 to 10
#11 Updated by intrigeri 2018-03-06 14:13:19
- QA Check deleted (
Dev Needed)
#12 Updated by intrigeri 2018-03-06 15:26:36
- Status changed from In Progress to Resolved
- % Done changed from 10 to 100
Applied in changeset commit:c339cd92c18c4898f366eba14d7b436cd9cf8237.
#13 Updated by intrigeri 2018-03-06 15:27:15
- Assignee deleted (
intrigeri)