10:26 a.m.
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