Re: [Tails-project] [Tails-dev] Do you read the changelog?

Delete this message

Reply to this message
Author: intrigeri
To: The Tails public development discussion list
Subject: Re: [Tails-project] [Tails-dev] Do you read the changelog?

[Bcc'ing -project@ one last time, please follow-up on -dev@ as this
is not about surveying needs anymore, but about how we address them.]

(Speaking as a developer + release manager + someone interested in the
"where should we focus our limited resources" topic, with a focus here
on dropping repetitive manual work.)

intrigeri (2020-03-22):
> Among the people who told us they use the changelog in some way or
> another, it seems to me we can distinguish 4 main use cases:

To reason about this problem I needed to first grasp the big picture
of the information flow and define some terminology:

>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

- 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.

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.

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

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 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.