intrigeri:
> From the information consumer's perspective, different folks
> apparently want/need access to 2 different kinds of information:
>
> - the "why": what the fixed problem was
Let's keep in mind that release notes are also here to solve precisely
this concern. When I write them, my work is to filter out things that I
deem unimportant to our users. The changelog includes more changes than
the release notes but they shouldn't matter to our users.
They could matter to auditors or developers.
Also, most of the time, the changelog only describes what changed and
less and less *why* it was changed. For example, when writing the
release notes, it's my work to understand the *why* of a change and how
it impacts users. Most of the time this information is not in the changelog.
For example, first line: "Upgrade Tor Browser to 9.0.7-build1" is the
*what* but has no info regarding the *why* and the impact on users.
> - the "how": how exactly the problem was fixed
>
> From the information production perspective, we have 2 sources of
> information, that may both include one, or the other, kind of
> information folks want/need access to:
>
> - The changelog is generated from commit messages, that sometimes
> document the problem the commit fixes, and sometimes only document
> how said commit fixes the problem (with a link to the issue that
> itself presumably documents the problem).
>
> - For user-facing problems, our issue titles are generally focused on
> documenting what the problem is; while for lower-level aspects, our
> issue titles are often about the solution. I expect we'll see the
> same for MR titles unless we formalize something else.
Yep.
> This diversity of inputs + diversity of desired outputs makes it hard
> to design a simple, automated, one-size-fits-all solution.
> So I'll now zoom into practical use cases:
>
>> A. 1 technical users reads the changelog "to determine […] what impact
>> the change might have to me in regards how I use Tails"
>
> I understand this is about the "how".
>
> I believe that the sort of Tails usage that requires such a deep
> understanding of the system, beyond what's in the release notes,
> qualifies as "expert usage", which is not our primary focus.
> So I propose we don't include (A) in our list of requirements here.
Agreed.
Even power users should have enough with the release notes.
Auditors should be able to navigate a raw list of tickets and commits.
> This being said, I believe that my proposal for (C) below mostly
> addresses this.
>
>> B. 3 technical users / occasional contributors read the changelog, to
>> learn and/or out of curiosity
>
> This could be a mix of "why" and "how".
>
> Similarly to (A), I propose we don't focus on this here, but I believe
> that my proposal for (C) below mostly addresses this.
>
>> C. 2 contributors check it out occasionally, as a single place that
>> exposes the history of changes we've released
>
> This is about the "how", the "why", and the "when".
>
> Zooming further into what we heard about (C), the changelog address
> these needs:
>
> C.1 Need more details than what the release notes include,
> i.e. the "how" information
>
> C.2 Need easy access to the aggregated information across multiple
> releases
>
> Here's something I believe would address these 2 needs:
>
> - Write a program that fetches from GitLab the list of issues and MRs
> closed by a specified set of releases, and presents them together,
> grouped by milestone, via 1 single user operation (C.2).
>
> - And for C.1, sometimes issue/MR titles don't include this
> information, but commit messages do. So this program could have
> a mode in which, for each MR, it displays the corresponding
> commit messages.
>
> I suspect this program exists already. If not, it should be pretty
> cheap to write (modulo perhaps some issue <-> MR matching and
> de-duplication, if we feel fancy).
>
> Once we have this program, it becomes very cheap for the RM to paste
> its output as-is in the changelog file, and/or for us to publish this
> information over HTTPS somewhere (so one can click on links to go
> explore issues/MRs/commits further).
>
> This would solve 90% of my use case and I know how to deal via Git
> with the remaining 10%.
>
> Muri, would this be good enough for you?
>
>> D. sajolida uses it when writing release notes but it's insufficient
>> and he could probably do as good with Redmine only, with some
>> caveats (might be a bit slower, might need more clarification from
>> release managers)
>
> I understand you currently need both the changelog and Redmine because
> your need is a mix of "why" and "how": in many cases the high-level
> overview is enough, but in many cases you need to dive deeper to
> understand how it impacts users.
>
> I believe the design proposed above would solve most of the "might
> need more clarification from release managers" problem: you would have
> the high-level info handy, with the possibility to directly access the
> details that are missing in Redmine.
>
> What do you think?
If I understand correctly, your proposal would give me the same
information than the current changelog plus easier access to commits.
I don't think I've ever used commit messages to write the release notes
but maybe there's some missed opportunity here :)
It seems to me that it will not make my work harder but will actually
relax the timing between RM and me by allowing me to fetch this
information earlier during the release process.
Did I understand correctly?
> If this idea seems like a good starting point, we could do a MVP (e.g.
> pasting the output as-is to debian/changelog, no HTML output, no
> links), try it out for a couple releases, and iterate from there.
>
> For completeness, there's another idea floating around: build the
> changelog from changes files provided by the merged branches (#8689).
> The crux of this idea is to do the writing work at MR time, instead of
> at release time, which I think is a good move in principle. The way
> I see it, if MR titles are not sufficient and we want to write more,
> GitLab offers us a better way to do that, than snippets included in
> Git branches: we can do the writing in the MR summary (possibly in
> a dedicated section with a standard name), and the aforementioned
> program could include this information in the output, if desired.
I think that we should try your first proposal, which has the benefit of
not adding more tiny steps and "bureaucracy" while writing a branch.
Maybe it would have lead to a better changelog but the conclusion of
this thread seems to be that we don't really need a better changelog.
--
sajolida
Tails —
https://tails.boum.org/
UX · Fundraising · Technical Writing
