[libvirt] [PATCH] news: Make changes understandable for users

[Andrea Bolognani]

On Wed, 2017-03-29 at 06:34 -0400, John Ferlan wrote:
> I find it ironic that I went against my normal practice and tried not to
> be verbose. Just copying the git commit id message for a one liner. And
> now it's turning into a more lengthy description.

I guess it's very much a case-by-case situation. For
example, we have one entry in the release notes that
consists of just:

  Fix compilation on macOS

and that's okay, because there's nothing else to it:
compilation on macOS was broken, and now it no longer is.

If I happen to be curious about how exactly it was broken,
and how exactly it was fixed, I can peruse the git history
and find out, but in all other cases I will be able to
understand perfectly fine how the change affects, or fails
to affect, me from that single sentence.

In the 512 bytes vs 2 KiB case, a user reading the release
notes and not having run into the issue himself will
probably be unable to figure out whether the fix affects
him or not without digging further; moreover, even users
who *have* been affected by the bug might be unable to
immediately connect the failure they experienced at the
time with the fix description. In either case, the release
notes would have failed to achieve their purpose.

> Another "thought" here would be that "bugs" would be required to list
> their bz in the description section and the summary would be just the
> "short" (e.g. < 72 chars) git commit message. Leaving the 'details' in
> the bug for anyone that cared about "logical" storage pools to go read.
> Thus, for this one would have:
> 
> <change>
>   <summary>
>     logical: Need to overwrite/clear more than just first 512 bytes
>   </summary>
>   <description>
>     https://bugzilla.redhat.com/show_bug.cgi?id=1430679
>   </description>
> </change>

I don't think that would be good enough, for the reasons
explained above.

Notice how neither storage pools nor filesystems are
entioned at all, for example: those are two keywords that
I would definitely expect to be there.

At the end of the day, some changes can be fully described
in a single sentence, but most can't.

> (oh and yes, I could have written a better commit id message, I did try,
> but kept running too long).
> 
> Or instead of <description> it could be <reference>#</reference where
> the underlying code builds the query using the bz #.  That way if
> someone really wanted details they have a link to go to assuming of
> course that bz # link was a redhat bz. I could well be some other bug
> system, so just # may not work.

Yeah, that's the way I thought about doing it a while ago,
and it still seems like a good idea to me. We should just
have a URL in <reference>, so it would work for the Red Hat
Bugzilla as well as whatever other Web thingy.

> > Git's release notes have clearly been written and edited
> > by a single individual, so of course they're going to be
> > more consistent in tone and style than whatever our fairly
> > large community of contributors can come up with over the
> > span of a release.
> 
> Release notes are kind of an "organic process" and should be tailored to
> the needs of each product with the consumer of the release notes in
> mind. Not everyone that uses libvirt keeps "up to date" with the daily
> patches and knows (more or less) exactly what's going on.

Definitely. The target for libvirt release notes is very
much *not* libvirt developers, but rather downstream
maintainers and users, both those who use libvirt directly
and those who build their own software on top of it.

That's why we need to provide a high-level and as
comprehensive as possible overview of changes between
releases, providing enough context that digging through
the git log is not required in the vast majority of cases
while at the same time making sure we're not bogging it
down with trivial or internal only details.

> What we're doing now is a lot better than having DV sorting the various
> commit id messages into groups. I'm sure this has made release
> generation a bit easier for him!
> 
> We need to find that "happy medium" of providing enough information
> without overloading. I actually think we're doing pretty good at that
> right now. We may have missed a few things along the way, but it's
> become part of a review and check-in process relatively quickly. It's
> not perfect and definitely won't please everyone's idea of aesthetics.

Yup, it's a difficult balance to strike. We're certainly
doing a much better job these days, but that doesn't mean
we can't improve even further :)

-- 
Andrea Bolognani / Red Hat / Virtualization