Hi,
[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
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 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.
Cheers!
